Bump: Modernize `tun-tap` by LinkWanna · Pull Request #18 · vorner/tuntap

LinkWanna · 2026-05-25T01:25:33Z

Summary

Modernize tun-tap from 0.1.4 to 0.2.0: tokio 1.x, edition 2024, and general cleanup. This is a breaking change — the Async API is rewritten from Stream + Sink (futures 0.1) to AsyncRead + AsyncWrite (tokio 1.x).

Breaking Changes

Async API: Stream + Sink (tokio-core 0.1 / futures 0.1) → AsyncRead + AsyncWrite (tokio 1.x / AsyncFd). Use AsyncReadExt::read / AsyncWriteExt::write instead of Stream::poll / Sink::start_send.
Feature renamed: tokio → async. Enable with --features async (on by default).
Async::new signature: No longer takes a Handle — just Async::new(iface).
set_recv_bufsize removed: Buffer sizing is now caller-managed via AsyncRead.

Changes

Dependency upgrades

Before	After
`tokio-core` 0.1	`tokio` 1.x
`futures` 0.1	removed
`mio` 0.6	removed
`etherparse` 0.9 (dev)	0.17 (dev)
`serial_test` 0.4 (dev)	3.x (dev)
`version-sync` (dev)	removed

Code modernization

Edition 2024: unsafe extern "C", removed extern crate declarations
build.rs: removed extern crate cc;
[badges] section removed from Cargo.toml (deprecated by crates.io)
Travis CI → GitHub Actions (.github/workflows/ci.yml)
tests/version.rs removed (depended on dropped version-sync)
async module renamed to r#async for edition 2024 keyword compatibility

Migration Guide

// Before (0.1.x)
extern crate futures;
extern crate tokio_core;
let core = Core::new().unwrap();
let async_iface = Async::new(iface, &core.handle()).unwrap();
let (sink, stream) = async_iface.split();

// After (0.2.0)
use tokio::io::AsyncReadExt;
let mut async_iface = Async::new(iface).unwrap();
let mut buf = vec![0u8; 1504];
let n = async_iface.read(&mut buf).await.unwrap();

* Async API completely rewritten: `Stream + Sink` (tokio-core 0.1 / futures 0.1) replaced with `AsyncRead + AsyncWrite` (tokio 1.x / `AsyncFd`). The `Async` struct no longer implements `Stream` or `Sink`; use `AsyncReadExt` / `AsyncWriteExt` methods instead. * Feature renamed: `tokio` → `async`. Enable with `--features async` (on by default). * `set_recv_bufsize` removed from `Async`; external buffer sizing is now caller-managed via `AsyncRead`. * `tokio-core` 0.1 → `tokio` 1.x (features: net, rt, rt-multi-thread, io-util, macros, time) * `futures` 0.1 → removed (tokio provides async traits) * `mio` 0.6 → removed (tokio's `AsyncFd` replaces raw mio) * `etherparse` 0.9 → 0.17 (dev-dependency) * `serial_test` 0.4 → 3.x (dev-dependency) * `version-sync` → removed * Edition 2024 compliance: `extern "C"` → `unsafe extern "C"`, removed `extern crate` declarations * `build.rs`: removed `extern crate cc;` * `[badges]` section removed from `Cargo.toml` (deprecated by crates.io) * Travis CI replaced with GitHub Actions (`.github/workflows/ci.yml`) * `tests/version.rs` removed (depended on dropped `version-sync`) * Fixed `cmd` function in examples to accept arbitrary command instead of hardcoded `"ip"` (vorner#17) * Fixed typo in doc comment (vorner#16)

vorner

Hello

I'm a bit split about this. On one hand, it's kind of nice that someone found this thing I've kind of considered dead for a long time - there are certainly more modern, more complete and more downloaded crates that do the same thing.

On the other hand, it seems many things are changed without an obvious motivation (or outright deleted without a replacement). Furthermore, many of these changes seem to be done mechanically without some deeper design behind them - things like the r#, or using the AsyncRead and AsyncWrite traits…

vorner · 2026-06-13T15:42:02Z

+* Async API completely rewritten: `Stream + Sink` (tokio-core 0.1 / futures 0.1) replaced with
+  `AsyncRead + AsyncWrite` (tokio 1.x / `AsyncFd`). The `Async` struct no longer implements
+  `Stream` or `Sink`; use `AsyncReadExt` / `AsyncWriteExt` methods instead.
+* Feature renamed: `tokio` → `async`. Enable with `--features async` (on by default).


I don't think renaming to async is entirely correct - this does depend on a specific async runtime, tokio.

Also, I don't think it makes sense to list documentation to Rust, namely how to enable features - and besides, nobody really does it by that flag, they do so through their Cargo.toml.

vorner · 2026-06-13T15:42:57Z

+* `build.rs`: removed `extern crate cc;`
+* `[badges]` section removed from `Cargo.toml` (deprecated by crates.io)
+* Travis CI replaced with GitHub Actions (`.github/workflows/ci.yml`)
+* `tests/version.rs` removed (depended on dropped `version-sync`)


These are somewhat internal things. I don't think these belong to changelog - that's for consumers of the crate.

vorner · 2026-06-13T15:45:12Z

-#[test]
-fn test_html_root_url() {
-    assert_html_root_url_updated!("src/lib.rs");
-}


Can you explain the motivation for dropping this one? It did catch me previously forgetting to update the link in lib.rs, so it feels like it's kind of useful.

vorner · 2026-06-13T15:47:36Z

-#[cfg(feature = "tokio")]
-pub mod async;
+#[cfg(feature = "async")]
+pub mod r#async;


Given we are doing a breaking change, I'd say it makes sense to rename the module instead of using the r# hack (which forces downstream users to use it too).

vorner · 2026-06-13T15:48:19Z

-//! You really do want better error handling than all these unwraps.
-
-extern crate tun_tap;
+//! that.


Duplicated.

vorner · 2026-06-13T15:53:07Z

    let iface = Iface::new("testtun%d", Mode::Tun).unwrap();
    eprintln!("Iface: {:?}", iface);
-    // Configure the „local“ (kernel) endpoint. Kernel is (the host) 10.107.1.3, we (the app)
+    // Configure the "local" (kernel) endpoint. Kernel is (the host) 10.107.1.3, we (the app)


On one hand, you're replacing dashes with the more correct long ones, on the other, you're removing the typographically correct quotes?

vorner · 2026-06-13T15:55:15Z

+        }
    });
-    core.run(reader.join(writer)).unwrap();
+    tokio::try_join!(write_task, read_task).unwrap();


What's the motivation behind making it run forever instead of just once? The PR seems to be about modernizing things, but you seem to be doing a lot more for unexplained reasons.

vorner · 2026-06-13T16:16:57Z

+    /// Returns a shared reference to the underlying [`Iface`].
+    pub fn get_ref(&self) -> &Iface {
+        self.inner.get_ref()
+    }


I don't think these are a particularly good idea. Given we have switched the interface to asynchronous mode, its own interface won't really work like designed (everything will just fail on it most of the time), creating a footgun.

vorner · 2026-06-13T17:11:29Z

-            },
-            Err(ref e) if e.kind() == ErrorKind::WouldBlock => Ok(FAsync::NotReady),
-            Err(e) => Err(e),
+impl AsyncRead for Async {


AsyncRead and AsyncWrite are the wrong abstraction layer here. These model „streaming“ interfaces - things like File or TcpStream. If you read a bit, you continue where you left off. Similarly, you have things like write_all that loop until everything is written by chunks.

The tun/tap things are message based. Each interaction must be a whole, independent packet. If you read just 5 bytes of the packet, you've lost the rest - next time you get the next packet. If you use write_all and try to send one „big“ packet and it happens to get split, you send two (damaged) packets.

Using these traits would lead to occasional and subtle bugs that would be hard to debug.

Notice that things like UdpStream in tokio also don't implement AsyncRead and AsyncWrite.

vorner · 2026-06-13T17:12:02Z

+                }
+                Ok(Err(e)) if e.kind() == io::ErrorKind::WouldBlock => continue,
+                Ok(Err(e)) => return Poll::Ready(Err(e)),
+                Err(_would_block) => continue,


The fact we get WouldBlock at two different levels seems somewhat suspicious.

Remove loop in `writer_task` and add a filter in `read_task`, so we can get exact `PING`.

We change the name `async` to avoid using `r#` hack

Replace the stream-based (AsyncRead + AsyncWrite) async interface with datagram-style recv/send methods to match the TUN device's message semantics.

LinkWanna · 2026-06-27T09:18:55Z

Thanks for your review!

The initial commits had a number of issues — some due to carelessness on my part, others from design immaturity. I really appreciate you pointing them out and providing valuable suggestions.

Here are the key changes I've made since:

Rewrote src/async.rs as src/aio.rs. I used AsyncFd to wrap the synchronous recv and send calls behind try_io, providing a more modern async interface that integrates better with the tokio ecosystem. The Stream and Sink implementations have been removed.
Updated the read_task logic in examples/tokio.rs with a packet filter that ensures the PING packets sent by write_task are correctly identified. In the original version, read_task would always pick up kernel background noise first, so it never managed to receive the packets sent by write_task.

LinkWanna added 2 commits May 20, 2026 17:50

ci: replace Travis CI with GitHub Action

7dcd890

vorner reviewed Jun 13, 2026

View reviewed changes

LinkWanna added 10 commits June 20, 2026 17:48

fix: add a filter to get PING from writer

fb7314e

Remove loop in `writer_task` and add a filter in `read_task`, so we can get exact `PING`.

fix: rename feature async to tokio

dc72c73

refactor: rename async to aio

9d1d3a4

We change the name `async` to avoid using `r#` hack

fix: add #[allow(unused_variables)] to fix warning

b725d51

fix: add tests/version.rs again

729dbbd

docs: update CHANGELOG.md

70d00bd

ci: fix ci.yml

a8f5af2

refactor: message-oriented async I/O interface

44a2aea

Replace the stream-based (AsyncRead + AsyncWrite) async interface with datagram-style recv/send methods to match the TUN device's message semantics.

docs: update CHANGELOG.md

1e130ab

ci: fix ci

7f981a9

LinkWanna force-pushed the master branch from 84bcba9 to 7f981a9 Compare June 27, 2026 09:16

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Bump: Modernize `tun-tap`#18

Bump: Modernize `tun-tap`#18
LinkWanna wants to merge 12 commits into
vorner:masterfrom
LinkWanna:master

LinkWanna commented May 25, 2026

Uh oh!

vorner left a comment

Uh oh!

vorner Jun 13, 2026

Uh oh!

vorner Jun 13, 2026

Uh oh!

vorner Jun 13, 2026

Uh oh!

vorner Jun 13, 2026

Uh oh!

vorner Jun 13, 2026

Uh oh!

vorner Jun 13, 2026

Uh oh!

vorner Jun 13, 2026

Uh oh!

vorner Jun 13, 2026

Uh oh!

vorner Jun 13, 2026

Uh oh!

vorner Jun 13, 2026

Uh oh!

LinkWanna commented Jun 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

LinkWanna commented May 25, 2026

Summary

Breaking Changes

Changes

Dependency upgrades

Code modernization

Migration Guide

Uh oh!

vorner left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

LinkWanna commented Jun 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants