Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
30 commits
Select commit Hold shift + click to select a range
4e8a7d6
chore(quest): claim quest/m1/ffi-refusals/moq-pin.md
kixelated Nov 12, 2026
f21ae87
feat(ffi): export a type the root does not reach by its public path i…
kixelated Nov 12, 2026
1b01081
fix(ffi): name a reached crate's types through the glue's own depende…
kixelated Nov 12, 2026
11d8c73
fix(ffi): keep a reached git dependency's reference, its targets, and…
kixelated Nov 12, 2026
ab877c5
test(ffi): merge a staged API whose reached crate only the exporting …
kixelated Nov 12, 2026
9f78c9b
test(ffi): compare the reached path as the manifest escapes it
kixelated Nov 12, 2026
19bb1a8
chore(quest): claim quest/m1/ffi-refusals/moq-main.md
kixelated Nov 13, 2026
dc34b21
Merge branch 'quest/m1/ffi-refusals/moq-pin' of https://github.com/ki…
kixelated Nov 13, 2026
b0feab7
wip(ffi): opaque by-value handles, held borrows of eager futures, len…
kixelated Nov 13, 2026
a67125c
feat(ffi): another crate's value as an opaque handle, held borrows of…
kixelated Nov 13, 2026
3883ec8
fix(ffi): refuse a borrowing output of an eager future and an erased …
kixelated Nov 13, 2026
9867cec
Merge remote-tracking branch 'origin/main' into quest/m1/ffi-refusals…
kixelated Nov 13, 2026
92d1dfb
fix(ffi): read earlier baselines, lend no erased value, and an orphan…
kixelated Nov 13, 2026
aa6cf62
fix(ffi): refuse a facade module named as a crate another target reaches
kixelated Nov 13, 2026
e569638
fix(ffi): refuse an eager future whose output names any borrowed life…
kixelated Nov 13, 2026
9a2f0f1
style(ffi): format
kixelated Nov 13, 2026
4ba1788
test(ffi): reject a borrowed slice of Copy opaque values and a conver…
kixelated Nov 13, 2026
0d3a7f7
fix(ffi): refuse a borrowed aggregate of Copy opaque values and a con…
kixelated Nov 13, 2026
7191ad8
Merge origin/main
kixelated Nov 13, 2026
faf44c8
fix(ffi): deref GenericArgs after the nightly bump
kixelated Nov 13, 2026
a32507b
Merge origin/main: #721's landed reach wins over this branch's copy
kixelated Nov 14, 2026
ba62a8e
fix(ffi): drop the excludes this branch exports at the pin, and re-me…
kixelated Nov 14, 2026
b71ab2e
style(ffi): format
kixelated Nov 14, 2026
d61e4ee
fix(ffi): review round 1: pinned optional slices, message-only error …
kixelated Nov 14, 2026
9068080
test(ffi): refuse a future whose held foreign error borrows its argum…
kixelated Nov 14, 2026
3851eec
Merge remote-tracking branch 'origin/main' into HEAD
kixelated Nov 14, 2026
db8aa63
quest: record the maintainer's follow-up answers for #733
kixelated Nov 14, 2026
85cb859
fix(ffi): a named future is no opaque handle, and a role-mapped type …
kixelated Nov 14, 2026
1e521b8
fix(ffi): read an impl Trait's elaborated bounds, so a supertrait's f…
kixelated Nov 14, 2026
b3c98b7
Merge remote-tracking branch 'origin/main' into HEAD
kixelated Nov 14, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions ffi/Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

9 changes: 5 additions & 4 deletions ffi/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -85,8 +85,8 @@ another of its name shares, the facade's root names, or another registry serves
reached. A crate only signatures reach keeps the roles of one no export is: its error in a
`Result` crosses as its message, and its type behind an `Arc` as an opaque handle, refused
bare. Its errors, the types implementing `std::error::Error`, are never reached, so an
exported error holding one is an object, as it was. A type no public path names stays
refused.
exported error holding one is an object, as it was. A type it cannot reach, such as one no
public path names, or an error taken by value, is held by value as an opaque handle instead.

| Rust | C |
| --- | --- |
Expand All @@ -105,7 +105,7 @@ refused.
| `Result<T, E>` | `bool f(..., T *out, E *err)`; an `E` of another crate that implements `Display`, such as `anyhow::Error` or `io::Error`, is `String`, its message |
| a returned tuple `(A, B)` | one out pointer each: `void f(..., A *out0, B *out1)` |
| a tuple inside another type, or as a field or parameter | `<prefix>_tuple_<A>_<B>`: a struct of fields `_0`, `_1`, and so on; of references only returned |
| `async fn`, or a return that implements `Future` | a future: `f` makes it, `f_poll` polls it, `f_future_free` drops it, and `f_start` makes it and polls it once, returning a handle only if it pends; a function that is not `async` runs at the call, as in Rust |
| `async fn`, or a return that implements `Future` | a future: `f` makes it, `f_poll` polls it, `f_future_free` drops it, and `f_start` makes it and polls it once, returning a handle only if it pends; a function that is not `async` runs at the call, as in Rust, and when its future borrows the arguments, the future owns them as an `async fn`'s does, holding each in place until it drops |
| a function returning `Poll<T>` that polls through a `&Context`, a `&mut Context`, or a reference to an object exactly one associated function makes from a `Waker` alone, of a type with no generic parameters, such as kio's `Waiter`, which may be the method's own `&self`, as `Waiter::poll_future`'s is | a future of `T`, as an `async fn`'s: each poll calls the function again with the poll's context, or with an object made from its waker and kept until the next poll, so what it registers stays registered; each other parameter taken by value must be `Copy`; a method polling through its own `&self` is a function without one |
| `poll_x`, when `x` exports as a future | left out: the future is its poll |
| `bool`, integers but 128-bit, floats, `char` | `bool`, `<stdint.h>` types, `float`, `double`, a `uint32_t` code point |
Expand All @@ -118,6 +118,7 @@ refused.
| `SocketAddr`, `SocketAddrV4`, `SocketAddrV6` | `<prefix>_socket_addr`: its IP's bytes, port, and whether it is IPv6; one of the other family passed to `V4` or `V6` aborts |
| `url::Url` | an object `<prefix>_Url`, made by `<prefix>_Url_parse`, which fails with the parse error's message, and printed by `_to_string` |
| `Arc<T>` of another crate's `Send` and `Sync` type that no other rule maps, such as `Arc<rustls::ServerConfig>` | an opaque object named by `T`'s crate and name, such as `<prefix>_rustls_ServerConfig`, with `_clone` and `_free` and none of `T`'s API: it only passes back to Rust |
| another crate's `Send` and `Sync` type taken or returned by value or lent, with no type parameters, that no other rule maps, that is no iterator or future, and that is not reached by its public path, such as one only a `#[doc(hidden)]` module names | an opaque object named as the `Arc` form is, with `_free` and none of `T`'s API, holding the value: Rust takes it back by value, or borrows it; a type also named behind an `Arc` is that form, and refused by value |
| `std::time::Instant` | an object `<prefix>_Instant`, which only Rust makes, copied into each call that takes it and compared by `_eq`, with none of its methods |
| `tracing::Level` | `<prefix>_Level`: a C enum of its five levels, `TRACE` to `ERROR` |
| `tracing::level_filters::LevelFilter` | `Option<tracing::Level>`, whose `None` is `OFF` |
Expand Down Expand Up @@ -156,7 +157,7 @@ A record or enum holds only values and `Copy` handles: one with a field that doe
or that holds itself, is an object instead, and the census lists it. A borrowed return is
returned as a clone, so it must be `Clone`, and a handle in it is a new handle to the
clone, but for an object a `&self` method of an object returns borrowed from its receiver
alone: that one, if not `Clone`, is a lent handle, which holds its receiver and checks it
alone, or an object's `pub` field holds: that one, if not `Clone`, is a lent handle, which holds its receiver and checks it
on each use, on one thread at a time where the receiver is not `Sync`. A handle outlives every call, so every lifetime an
object takes is `'static`, as is every lifetime that must outlive one; any other lifetime
is the call's. A signature may not lend C's borrow for one that is `'static`, but for a
Expand Down
32 changes: 32 additions & 0 deletions ffi/fixtures/api/examples/transcript.rs
Original file line number Diff line number Diff line change
Expand Up @@ -362,6 +362,22 @@ fn main() {
if let Poll::Ready(payload) = recv.as_mut().poll(&mut cx) {
println!("recv {}", String::from_utf8_lossy(&payload));
}
// The send happens at the call, and the future borrows the channel and the tag.
let mut tagged = pin!(channel.tagged("tag"));
if let Poll::Ready(text) = tagged.as_mut().poll(&mut cx) {
println!("tagged {text}");
}
// So does a future borrowing an optional slice, which the export owns while it is pending.
let items = [1u32, 2, 3];
let mut itemized = pin!(channel.itemized(Some(&items)));
if let Poll::Ready(count) = itemized.as_mut().poll(&mut cx) {
println!("itemized {count}");
}
// Another crate's future borrowing its bytes, which the export owns while it is pending.
let bytes = *b"abc";
if let Poll::Ready(len) = pin!(api::byte_len(&bytes)).poll(&mut cx) {
println!("byte_len {len}");
}
channel.send(Bytes::from_static(b"sized"));
let mut sized = pin!(channel.recv_sized());
if let Poll::Ready((payload, len)) = sized.as_mut().poll(&mut cx) {
Expand Down Expand Up @@ -585,6 +601,14 @@ fn main() {
println!("nudge {} {}", point.x, point.y);
let config = api::secure("h3");
println!("secure {} {}", api::alpn_lent(&config), api::alpn(config.clone()));
let cert = api::certify(b"der");
let chain = vec![api::certify(b"a"), api::certify(b"bc")];
println!(
"cert {} {} {}",
api::cert_len(&cert),
String::from_utf8_lossy(&api::cert_der(cert)),
api::chain_len(chain)
);
let session = api::resume("h3", 60).unwrap();
println!("resume {} {}", session.alpn(), session.lifetime().seconds);
println!("resume err {}", api::resume("", 60).err().unwrap());
Expand All @@ -594,6 +618,8 @@ fn main() {
println!("lent {} {}", first.add(3), meters.first().count());
meters.clear();
println!("cleared {}", meters.first().count());
meters.last.add(4);
println!("field lent {}", meters.last.add(1));
let tallies = api::Tallies::new();
tallies.first().bump();
println!("tallied {}", tallies.first().bump());
Expand Down Expand Up @@ -752,6 +778,12 @@ fn main() {
start == api::later(start, std::time::Duration::ZERO),
start == end
);
// An instant lent inside an `Option`, which takes no handle.
println!(
"has_instant {} {}",
api::has_instant(&Some(start)),
api::has_instant(&None)
);
let mut verbosity = api::Verbosity::new(tracing::Level::WARN);
println!(
"verbosity {} {}",
Expand Down
89 changes: 88 additions & 1 deletion ffi/fixtures/api/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -453,10 +453,11 @@ impl Meter {
}
}

/// Owns a meter it lends.
/// Owns a meter it lends, and one in a field, lent as the method's is.
#[derive(Default)]
pub struct Meters {
first: Meter,
pub last: Meter,
}

impl Meters {
Expand Down Expand Up @@ -871,6 +872,27 @@ impl Channel {
std::future::ready(())
}

/// Sends `tag` at once, as a function that is not `async` runs when called, and returns a
/// future that borrows this channel and `tag`: what it next receives, after `tag`.
pub fn tagged<'a>(&'a self, tag: &'a str) -> impl Future<Output = String> + 'a {
self.send(Bytes::copy_from_slice(tag.as_bytes()));
async move {
let payload = self.recv().await;
format!("{tag} {}", String::from_utf8_lossy(&payload))
}
}

/// Sends the sum of `items`, if any, at once, and returns a future that borrows them:
/// their count once this channel next receives.
pub fn itemized<'a>(&'a self, items: Option<&'a [u32]>) -> impl Future<Output = usize> + 'a {
let sum: u32 = items.unwrap_or_default().iter().sum();
self.send(Bytes::copy_from_slice(&sum.to_le_bytes()));
async move {
self.recv().await;
items.map_or(0, <[u32]>::len)
}
}

/// `recv`'s poll, which does not map: left out, since `recv` exports as a future.
pub fn poll_recv(&self, cx: &mut std::task::Context<'_>) -> Poll<Bytes> {
let mut state = self.state.lock().unwrap();
Expand Down Expand Up @@ -2266,6 +2288,65 @@ pub fn alpn_lent(config: &Arc<tls::Config>) -> String {
config.alpn().to_string()
}

/// A certificate of a crate the facade re-exports nothing from, by value, with no public
/// path there, as moq-tokio's rustls root certificates: an opaque handle, which Rust takes
/// back or borrows.
pub fn certify(der: &[u8]) -> tls::held::Cert {
tls::held::Cert::new(der)
}

/// The length of `bytes`, through another crate's future that borrows them but resolves
/// to an owned count: a future, not an opaque handle.
pub fn byte_len(bytes: &[u8]) -> tls::held::Pending<'_> {
tls::held::Pending(bytes)
}

/// The length of a certificate [`certify`] made, lent.
pub fn cert_len(cert: &tls::held::Cert) -> usize {
cert.der().len()
}

/// The bytes of a certificate [`certify`] made, taken back by value.
pub fn cert_der(cert: tls::held::Cert) -> Vec<u8> {
cert.der().to_vec()
}

/// The total length of a chain of certificates, each taken back by value.
pub fn chain_len(chain: Vec<tls::held::Cert>) -> usize {
chain.iter().map(|cert| cert.der().len()).sum()
}

/// Another crate's session with no public path there, which no export returns: left out, since C can never
/// hold one.
pub fn handover(session: tls::held::Handoff) -> u32 {
session.id
}

/// A certificate's length, or why it is refused: another crate's error, which crosses as
/// its message though `blame` names it as a handle no export returns.
pub fn verify(cert: &tls::held::Cert) -> Result<u32, tls::held::Invalid> {
match cert.der().len() {
0 => Err(tls::held::Invalid {
reason: "empty".to_string(),
}),
len => Ok(len as u32),
}
}

/// `text`'s length, or why it is no certificate: another crate's error borrowing `text`,
/// which crosses as its message, so nothing outlives the call.
pub fn parse_cert(text: &str) -> Result<u32, tls::held::Malformed<'_>> {
match text.is_empty() {
true => Err(tls::held::Malformed(text)),
false => Ok(text.len() as u32),
}
}

/// Another crate's error taken back by value, which no export returns: left out.
pub fn blame(err: tls::held::Invalid) -> String {
err.to_string()
}

/// A session of `alpn` lasting `seconds`, from a crate the facade re-exports nothing from:
/// its type exports by its path there, and its error crosses as its message.
pub fn resume(alpn: &str, seconds: u32) -> Result<tls::Session, tls::Error> {
Expand Down Expand Up @@ -2564,6 +2645,12 @@ pub fn since(later: std::time::Instant, earlier: std::time::Instant) -> Duration
later.saturating_duration_since(earlier)
}

/// Whether `at` holds an instant, lent inside an `Option`: an instant crosses as a `Copy`
/// object, so lending one inside a value takes no handle.
pub fn has_instant(at: &Option<std::time::Instant>) -> bool {
at.is_some()
}

/// How much to log, as moq-tokio's `Log` holds it: a field of a foreign enum, and its filter.
#[non_exhaustive]
pub struct Verbosity {
Expand Down
1 change: 1 addition & 0 deletions ffi/fixtures/reject/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ name = "reject"

[dependencies]
dep-fixture = { path = "../dep" }
tls-fixture = { path = "../tls" }

[lints]
workspace = true
Loading