tailkitty 0.2.2__tar.gz → 0.2.3__tar.gz

{tailkitty-0.2.2 → tailkitty-0.2.3}/AGENTS.md

@@ -46,6 +46,7 @@ compatibility and fail-closed bundle discovery are core requirements.
 | `src/tailkitty/backend.py` | Backend precedence and command execution |
 | `src/tailkitty/bundle.py` | Runtime manifest and executable integrity checks |
 | `src/tailkitty/client.py` | Sync and asyncio client APIs |
+| `src/tailkitty/udp.py` | Typed SOCKS5 UDP framing, connections, and lifecycle |
 | `src/tailkitty/process.py` | Managed server processes and low-level async execution |
 | `src/tailkitty/cli.py` | Python-native commands and upstream pass-through |
 | `src/tailkitty/constants.py` | Package, Go, module, and upstream Tailcat pins |

{tailkitty-0.2.2 → tailkitty-0.2.3}/BUILDING.md

@@ -154,7 +154,8 @@ The smoke test:
 3. Runs `tailkitty doctor --json` and confirms the bundled backend is selected.
 4. Starts an isolated local DERP/STUN relay through Tailcat's test mode.
 5. Starts a peer and performs an actual encrypted ping.
-6. Applies five-second startup and client bounds, followed by bounded termination.
+6. Sends and receives a real application UDP datagram through the same isolated relay.
+7. Applies five-second startup and client bounds, followed by bounded termination.
 
 It does not depend on public relay availability and does not touch saved developer keys.
 

{tailkitty-0.2.2 → tailkitty-0.2.3}/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.2.3 - 2026-09-08
+
+- Add typed synchronous and asyncio UDP connections that preserve datagram boundaries through
+  Tailcat's SOCKS5 UDP relay.
+- Add opt-in `ServerProcess(udp=...)` forwarding from Tailcat UDP ports to matching loopback UDP
+  ports, with a real encrypted UDP wheel smoke test.
+- Create GitHub Releases automatically after successful Trusted Publishing, attaching all wheels,
+  the source distribution, and SHA-256 checksums.
+
 ## 0.2.2 - 2026-09-08
 
 - Use Tailcat's declarative `serve` subcommand in managed Python server processes.

{tailkitty-0.2.2 → tailkitty-0.2.3}/COMPARISON.md

@@ -5,7 +5,7 @@ independent Python projects built around upstream
 [Tailscale Tailcat](https://github.com/tailscale/tailcat). They are not rename-compatible packages:
 install and import the one you intend.
 
-This comparison was checked on 2026-09-08 against `pytailcat` 0.1.4 and Tailkitty 0.2.2.
+This comparison was checked on 2026-09-08 against `pytailcat` 0.1.4 and Tailkitty 0.2.3.
 
 ## Summary
 
@@ -16,7 +16,7 @@ This comparison was checked on 2026-09-08 against `pytailcat` 0.1.4 and Tailkitt
 
 ## Feature comparison
 
-| Capability | `pytailcat` 0.1.4 | Tailkitty 0.2.2 |
+| Capability | `pytailcat` 0.1.4 | Tailkitty 0.2.3 |
 | --- | --- | --- |
 | Distribution/import | `pytailcat` | `tailkitty` |
 | Upstream data plane | Bundled Tailcat executable | Pinned Tailcat v0.6.0 executable |
@@ -28,6 +28,7 @@ This comparison was checked on 2026-09-08 against `pytailcat` 0.1.4 and Tailkitt
 | DERP expansion | Delegated to executable | Pure Python with bounded ETag cache and stale fallback |
 | DNS destinations | Delegated to executable | Pure-Python sync and asyncio resolution |
 | Client API | Thin synchronous process wrapper | Typed finite, streaming, sync, and asyncio clients |
+| Application UDP | Depends on older bundled executable | Typed sync/async datagrams and opt-in localhost serving |
 | Server API | Synchronous `ServerProcess` | Managed sync/async servers with typed v0.6 options |
 | Lifecycle cleanup | Basic process management | Bounded startup, terminate/kill escalation, reaping |
 | Bundle verification | Package transport integrity | Runtime target, schema, size, and SHA-256 verification |

{tailkitty-0.2.2 → tailkitty-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tailkitty
-Version: 0.2.2
+Version: 0.2.3
 Summary: Python tooling and a verified distribution for Tailscale Tailcat
 Project-URL: Homepage, https://github.com/kornpow/tailkitty
 Project-URL: Source, https://github.com/kornpow/tailkitty
@@ -53,6 +53,7 @@ control server.
 | --- | --- |
 | Send bytes between two computers | [One-shot pipe](#one-shot-pipe) |
 | Reach a remote web app or database | [Forward a port](#forward-a-port) |
+| Exchange UDP datagrams | [Typed UDP](#typed-udp) |
 | Use Tailcat from Python | [Python quickstart](#python-quickstart) |
 | Transfer files or use SSH | [Recipes](https://github.com/kornpow/tailkitty/blob/main/docs/recipes.md) |
 | Diagnose an installation | [Troubleshooting](https://github.com/kornpow/tailkitty/blob/main/docs/troubleshooting.md) |
@@ -188,6 +189,33 @@ exit. See the [Python API guide](https://github.com/kornpow/tailkitty/blob/main/
 for asyncio, streaming, token handling, server
 options, exceptions, and low-level execution.
 
+### Typed UDP
+
+Tailkitty preserves application datagram boundaries instead of treating UDP as a byte stream. On
+the server, bind your UDP application to localhost and opt in to the same Tailcat port:
+
+```python
+from tailkitty import ServerProcess
+
+with ServerProcess(udp=5353, key="new") as server:
+    print(server.token)
+    input("Press Enter to stop the UDP tunnel... ")
+```
+
+On the client:
+
+```python
+from tailkitty import Client
+
+with Client("tc...").connect_udp(5353, timeout=10) as connection:
+    reply = connection.request(b"one datagram", timeout=3)
+    print(reply.data)
+```
+
+`send()` and `receive()` each handle exactly one datagram. Payloads are limited to
+`MAX_UDP_PAYLOAD` (1232 bytes), the safe size for Tailcat's tunnel MTU. Asyncio equivalents are
+available through `AsyncClient.connect_udp()`.
+
 ## CLI model
 
 Tailkitty owns a small Python-native command surface:
@@ -214,9 +242,9 @@ tailkitty socks 'tc...' curl http://server.tailcat:8080/
 tailkitty genkey --client --key=client-default
 ```
 
-Run `tailkitty readme` for the documentation embedded in the bundled Tailcat version. Tailcat v0.6
-also supports application-layer UDP through its Go API and SOCKS5 UDP association; Tailkitty does
-not currently expose a separate typed Python UDP API.
+Run `tailkitty readme` for the documentation embedded in the bundled Tailcat version. Tailkitty's
+typed UDP API uses Tailcat v0.6's SOCKS5 UDP association and an auditable bundled patch that adds
+opt-in `127.0.0.1` UDP serving to the CLI.
 
 ## Addresses and DNS
 
@@ -262,8 +290,9 @@ tailkitty resolve 'tc...' > full-address.txt
 | `Client.request(...)` | Yes | Finite request/response exchange |
 | `Client.run(...)` | Yes | Finite exchange with exit status and stderr |
 | `Client.connect(...)` | Yes | Full-duplex `subprocess.Popen` connection |
+| `Client.connect_udp(...)` | Yes | Datagram-preserving UDP connection |
 | `ServerProcess` | Yes | Managed synchronous server |
-| `AsyncClient` / `AsyncServerProcess` | Yes | Asyncio equivalents |
+| `AsyncClient` / `AsyncServerProcess` | Yes | Asyncio equivalents, including UDP |
 | `run(...)` / `run_async(...)` | Yes | Low-level Tailcat command execution |
 | `diagnostics()` | Yes | Structured backend and environment report |
 

{tailkitty-0.2.2 → tailkitty-0.2.3}/README.md

@@ -28,6 +28,7 @@ control server.
 | --- | --- |
 | Send bytes between two computers | [One-shot pipe](#one-shot-pipe) |
 | Reach a remote web app or database | [Forward a port](#forward-a-port) |
+| Exchange UDP datagrams | [Typed UDP](#typed-udp) |
 | Use Tailcat from Python | [Python quickstart](#python-quickstart) |
 | Transfer files or use SSH | [Recipes](https://github.com/kornpow/tailkitty/blob/main/docs/recipes.md) |
 | Diagnose an installation | [Troubleshooting](https://github.com/kornpow/tailkitty/blob/main/docs/troubleshooting.md) |
@@ -163,6 +164,33 @@ exit. See the [Python API guide](https://github.com/kornpow/tailkitty/blob/main/
 for asyncio, streaming, token handling, server
 options, exceptions, and low-level execution.
 
+### Typed UDP
+
+Tailkitty preserves application datagram boundaries instead of treating UDP as a byte stream. On
+the server, bind your UDP application to localhost and opt in to the same Tailcat port:
+
+```python
+from tailkitty import ServerProcess
+
+with ServerProcess(udp=5353, key="new") as server:
+    print(server.token)
+    input("Press Enter to stop the UDP tunnel... ")
+```
+
+On the client:
+
+```python
+from tailkitty import Client
+
+with Client("tc...").connect_udp(5353, timeout=10) as connection:
+    reply = connection.request(b"one datagram", timeout=3)
+    print(reply.data)
+```
+
+`send()` and `receive()` each handle exactly one datagram. Payloads are limited to
+`MAX_UDP_PAYLOAD` (1232 bytes), the safe size for Tailcat's tunnel MTU. Asyncio equivalents are
+available through `AsyncClient.connect_udp()`.
+
 ## CLI model
 
 Tailkitty owns a small Python-native command surface:
@@ -189,9 +217,9 @@ tailkitty socks 'tc...' curl http://server.tailcat:8080/
 tailkitty genkey --client --key=client-default
 ```
 
-Run `tailkitty readme` for the documentation embedded in the bundled Tailcat version. Tailcat v0.6
-also supports application-layer UDP through its Go API and SOCKS5 UDP association; Tailkitty does
-not currently expose a separate typed Python UDP API.
+Run `tailkitty readme` for the documentation embedded in the bundled Tailcat version. Tailkitty's
+typed UDP API uses Tailcat v0.6's SOCKS5 UDP association and an auditable bundled patch that adds
+opt-in `127.0.0.1` UDP serving to the CLI.
 
 ## Addresses and DNS
 
@@ -237,8 +265,9 @@ tailkitty resolve 'tc...' > full-address.txt
 | `Client.request(...)` | Yes | Finite request/response exchange |
 | `Client.run(...)` | Yes | Finite exchange with exit status and stderr |
 | `Client.connect(...)` | Yes | Full-duplex `subprocess.Popen` connection |
+| `Client.connect_udp(...)` | Yes | Datagram-preserving UDP connection |
 | `ServerProcess` | Yes | Managed synchronous server |
-| `AsyncClient` / `AsyncServerProcess` | Yes | Asyncio equivalents |
+| `AsyncClient` / `AsyncServerProcess` | Yes | Asyncio equivalents, including UDP |
 | `run(...)` / `run_async(...)` | Yes | Low-level Tailcat command execution |
 | `diagnostics()` | Yes | Structured backend and environment report |
 

{tailkitty-0.2.2 → tailkitty-0.2.3}/RELEASING.md

@@ -122,16 +122,20 @@ command line, in shell history, or in repository files.
 If the automated release is still running, do not race it with a local upload. Cancel or disable
 the redundant publisher first so one path owns publication.
 
-## 7. Create or verify the GitHub release
+## 7. Verify the GitHub release
 
-The release should contain the same seven artifacts published to PyPI, plus checksums when the
-automated workflow produced them. For a controlled local fallback:
+After Trusted Publishing succeeds, the workflow creates the GitHub Release and attaches the same
+seven artifacts plus `SHA256SUMS`. It verifies that the tag already exists before creating the
+release. Confirm those eight assets are present.
+
+For a controlled local fallback when automation was not used:
 
 ```console
 gh release create vX.Y.Z \
   --title "Tailkitty vX.Y.Z" \
   --generate-notes \
-  dist/release/*
+  dist/release/* \
+  checksums/SHA256SUMS
 ```
 
 ## 8. Verify from the public index

{tailkitty-0.2.2 → tailkitty-0.2.3}/SECURITY.md

@@ -113,6 +113,11 @@ These services have broader consequences than a one-shot byte stream:
 
 Tailkitty does not add authentication to the application behind a served port.
 
+UDP serving is separately opt-in through `ServerProcess(udp=...)`. Selected Tailcat UDP ports are
+forwarded only to matching `127.0.0.1` UDP ports; the local application still needs its own
+authentication where appropriate. UDP source addresses seen by the local application belong to
+the proxy path and are not a substitute for Tailcat client identity or `--allow`.
+
 ## Bundle trust model
 
 Platform wheels contain an executable built from the immutable Tailcat pin. The build manifest

{tailkitty-0.2.2 → tailkitty-0.2.3}/docs/architecture.md

@@ -35,6 +35,7 @@ Tailcat interoperability depends on Tailscale's implementations of:
 - WireGuard session establishment and encryption.
 - Disco-key peer discovery and endpoint exchange.
 - STUN-based NAT traversal and UDP hole punching.
+- Application UDP flows with preserved datagram boundaries.
 - DERP relay transport and path selection.
 - A userspace TCP/IP stack based on gVisor netstack.
 
@@ -63,6 +64,17 @@ directly to Tailcat rather than an unnecessary wrapper process.
 This small ownership surface prevents Tailkitty's parser from lagging or subtly changing upstream
 commands.
 
+## Typed UDP flow
+
+Each `UDPConnection` owns a private loopback SOCKS5 UDP association. Python encodes and validates
+the SOCKS5 datagram envelope; the upstream process carries each payload over Tailcat's WireGuard
+tunnel without merging datagrams. A small recorded source patch adds opt-in `serve --udp`
+forwarding from selected tunnel ports to matching `127.0.0.1` UDP ports.
+
+This keeps the cryptographic and network stack native while exposing typed synchronous and asyncio
+lifecycle APIs. Closing a connection closes its sockets and terminates and reaps the owned Tailcat
+process. Payloads larger than Tailcat's 1232-byte safe tunnel size are rejected before sending.
+
 ## Address flow
 
 ```text

{tailkitty-0.2.2 → tailkitty-0.2.3}/docs/python-api.md

@@ -18,6 +18,7 @@ uv add tailkitty
 | Send one finite request | `Client.request()` |
 | Keep exit status and stderr | `Client.run()` |
 | Stream in both directions | `Client.connect()` |
+| Exchange UDP datagrams | `Client.connect_udp()` |
 | Send bytes with a one-line helper | `send()` |
 | Run a managed server | `ServerProcess` |
 | Do the same work with asyncio | `AsyncClient`, `AsyncServerProcess` |
@@ -185,6 +186,64 @@ termination, and reaping.
 For a minimal one-shot exchange, `send(destination, data, port=0, timeout=None)` is a convenience
 wrapper around `Client(destination).request(...)`.
 
+## UDP datagrams
+
+`connect_udp()` returns a managed connection that keeps datagram boundaries intact:
+
+```python
+from tailkitty import Client, MAX_UDP_PAYLOAD
+
+with Client("tc...").connect_udp(5353, timeout=10) as connection:
+    connection.send(b"first datagram")
+    response = connection.receive(timeout=3)
+    print(response.data, response.host, response.port)
+
+    second = connection.request(b"second datagram", timeout=3)
+    assert len(second.data) <= MAX_UDP_PAYLOAD
+```
+
+Each `send()` transmits one datagram and each `receive()` returns one immutable `Datagram` with
+`data`, `host`, and `port` fields. `request()` is a send followed by one receive; UDP itself does
+not guarantee that the response corresponds to the request. A receive timeout raises
+`TimeoutError` (`socket.timeout` in synchronous code).
+
+The default target host, `server.tailcat`, means the named Tailcat server. Set `host` to an IP or
+hostname only when the server is intentionally configured as an exit node:
+
+```python
+connection = Client("tc...").connect_udp(53, host="192.0.2.53")
+```
+
+Tailcat's IPv6 tunnel MTU makes 1232 bytes the largest safe UDP payload. Tailkitty rejects larger
+writes rather than relying on fragmentation. SOCKS5 fragmentation is not supported. Each
+connection owns a private loopback-only SOCKS5 proxy and native Tailcat process; use a context
+manager or call `close()`.
+
+The asyncio API has matching semantics:
+
+```python
+from tailkitty import AsyncClient
+
+async with await AsyncClient("tc...").connect_udp(5353, timeout=10) as connection:
+    response = await connection.request(b"datagram", timeout=3)
+    print(response.data)
+```
+
+On the server, start the UDP application on localhost first, then expose the matching port:
+
+```python
+from tailkitty import ServerProcess
+
+with ServerProcess(udp=[5353, 9000], key="new", allow=["nodekey:..."]) as server:
+    print(server.token)
+    input("Press Enter to stop the UDP tunnel... ")
+```
+
+`udp` accepts one integer or an iterable of integers. It is opt-in and independent of TCP `serve`;
+the bundled backend forwards only the selected Tailcat UDP ports to the same ports on `127.0.0.1`.
+This server feature is a Tailkitty patch to the pinned executable. An unpatched external backend
+selected through `TAILKITTY_BACKEND` may reject `--udp`.
+
 ## Managed synchronous server
 
 ```python
@@ -230,6 +289,7 @@ equivalent.
 | `use_preshared_key` | Explicitly enable or disable address PSKs; `None` uses upstream default |
 | `files` | File-service root and optional mode suffix |
 | `ssh_authorized_keys` | One source or a sequence of files, literal keys, or `user@github` values |
+| `udp` | UDP port or iterable forwarded to matching localhost UDP ports |
 | `extra_args` | Escape hatch for upstream flags not modeled yet |
 | `stdin`, `stdout`, `stderr` | Synchronous child-process stream targets |
 | `env` | Environment additions for the child process |
@@ -340,6 +400,7 @@ target, wheel tag, Tailcat version, compiler version, size, digest, and verified
 | `BackendNotFound` | Backend discovery and integrity translation |
 | `BundleError` | Direct bundle validation |
 | `ServerStartError` | Managed server exits before advertising an address |
+| `UDPError` | SOCKS5 negotiation, framing, subprocess, or closed-connection failure |
 | `TimeoutError` | Managed startup or async operation timeout |
 | `subprocess.TimeoutExpired` | Synchronous finite client timeout |
 | `subprocess.CalledProcessError` | Checked client or low-level command fails |

{tailkitty-0.2.2 → tailkitty-0.2.3}/docs/recipes.md

@@ -239,6 +239,33 @@ The SOCKS proxy can also route ordinary destinations through an exit node:
 tailkitty socks 'tc...' curl https://example.com/
 ```
 
+## Exchange UDP datagrams from Python
+
+Start a UDP service on `127.0.0.1:5353` on the server, then expose that same UDP port:
+
+```python
+from tailkitty import ServerProcess
+
+with ServerProcess(udp=5353, key="new", allow=["nodekey:..."]) as server:
+    print(server.token)
+    input("Press Enter to stop the UDP tunnel... ")
+```
+
+On the client:
+
+```python
+from tailkitty import Client
+
+with Client("tc...").connect_udp(5353, timeout=10) as connection:
+    connection.send(b"one datagram")
+    response = connection.receive(timeout=3)
+    print(response.data)
+```
+
+Use `AsyncClient.connect_udp()` for asyncio applications. Keep payloads at or below 1232 bytes.
+UDP is unreliable and unordered by design, so applications must define their own retry and
+request-correlation behavior when needed.
+
 ## Check relay and direct connectivity
 
 One ping reports the path used:

{tailkitty-0.2.2 → tailkitty-0.2.3}/docs/troubleshooting.md

@@ -177,6 +177,19 @@ Failure to become direct usually points to NAT, firewall, captive-network, or UD
 connection can still work through DERP. Compare both peers from another network before assuming a
 packaging defect.
 
+## UDP request times out
+
+- Confirm the local UDP application is bound to `127.0.0.1:<port>` on the server before starting
+  `ServerProcess(udp=<port>)`.
+- `serve=<port>` exposes TCP; `udp=<port>` exposes UDP. Configure the protocol you actually use.
+- Keep each datagram at or below `MAX_UDP_PAYLOAD` (1232 bytes).
+- Set a finite receive timeout while diagnosing; UDP has no delivery or response guarantee.
+- Confirm the client satisfies the server's `allow` policy.
+- An external `TAILKITTY_BACKEND` needs Tailkitty's `serve --udp` patch for server-side forwarding.
+
+Always close `UDPConnection`, preferably with a context manager, so its private SOCKS5 proxy and
+Tailcat subprocess are reaped.
+
 ## DNS destination fails
 
 Inspect the TXT record with a DNS tool:

tailkitty-0.2.3/patches/0001-cli-udp-serving.patch

@@ -0,0 +1,118 @@
+diff --git a/cmd/tailcat/tailcat.go b/cmd/tailcat/tailcat.go
+index fbd6372..b2b8d74 100644
+--- a/cmd/tailcat/tailcat.go
++++ b/cmd/tailcat/tailcat.go
+@@ -57,6 +57,7 @@ var (
+ 	flagFiles             *string
+ 	flagSSHAuthorizedKeys *string
+ 	flagPSK               *bool
++	flagUDP               *string
+ 	flagVerbose           *bool
+ 	flagFullAddress       *bool
+ 	flagJSON              *bool
+@@ -103,6 +104,7 @@ func newRootCommand() *ff.Command {
+ 	flagFiles = serveFS.StringLong("files", "", "directory to serve to SFTP clients (scp, sftp) with the 'files' service, with an optional :ro (read-only, the default), :rw (read-write), :wo (flat write-only drop box), or :wo+ (recursive write-only drop box) suffix. If empty, the current directory is served read-only. Giving --files implies the 'files' service.")
+ 	flagSSHAuthorizedKeys = serveFS.StringLong("ssh-authorized-keys", "", "comma-separated SSH public key sources for the 'ssh' service: authorized_keys file paths, literal OpenSSH public key lines, or names like 'alice@github' (fetched from https://github.com/alice.keys). All sources are loaded and validated at startup.")
+ 	flagPSK = serveFS.BoolLongDefault("psk", true, "include a WireGuard pre-shared key in the tailcat address (recommended). Set false only for shorter addresses and compatibility with tailcat clients v0.5.0 and earlier; this weakens security.")
++	flagUDP = serveFS.StringLong("udp", "", "comma-separated UDP ports or ranges to proxy to the same ports on localhost")
+ 
+ 	recvFS := ff.NewFlagSet("recv").SetParent(serveFS)
+ 	flagRecvAcceptDirs := recvFS.BoolLong("accept-dirs", "accept directory trees (tailcat cp -r), keeping requested file names when available. The trade-off: senders can then make and stat directories and learn whether some names already exist in the drop box. The default flat mode reveals nothing about existing files, but accepts only single files, each saved under a server-chosen unique name.")
+@@ -1174,6 +1176,13 @@ func server(logf logger.Logf, serveSpec string) {
+ 	if err != nil {
+ 		log.Fatalf("invalid port or service to serve: %v", err)
+ 	}
++	udpPortSet, udpServices, err := parsePortSet(*flagUDP)
++	if err != nil {
++		log.Fatalf("invalid UDP port to serve: %v", err)
++	}
++	if len(udpServices) != 0 {
++		log.Fatalf("--udp accepts only port numbers and ranges")
++	}
+ 	if *flagFiles != "" {
+ 		if !tailCatSSHEnabled {
+ 			log.Fatalf("--files requires SSH support, not included in binary per build tags")
+@@ -1212,7 +1221,7 @@ func server(logf logger.Logf, serveSpec string) {
+ 	}
+ 	// A server running only named services isn't the empty-port-list
+ 	// accept-one-connection stdout mode.
+-	oneShotStdout := len(portSet) == 0 && len(services) == 0
++	oneShotStdout := len(portSet) == 0 && len(services) == 0 && len(udpPortSet) == 0
+ 
+ 	var reg *tailcfg.DERPRegion
+ 	var devDERP *derpserver.Server
+@@ -1322,6 +1331,9 @@ func server(logf logger.Logf, serveSpec string) {
+ 		}
+ 		s.ServedTCPPorts = portRanges(ports)
+ 	}
++	if len(udpPortSet) != 0 {
++		s.ServedUDPPorts = portRanges(slices.Sorted(maps.Keys(udpPortSet)))
++	}
+ 	if *flagAllow != "" {
+ 		for _, ks := range strings.Split(*flagAllow, ",") {
+ 			if ks == "none" {
+@@ -1347,6 +1360,24 @@ func server(logf logger.Logf, serveSpec string) {
+ 		}
+ 	}
+ 
++	udpForwardTo := func(ipPortStr string) func(tailcat.ConnPacketConn) {
++		return func(c tailcat.ConnPacketConn) {
++			addr, err := net.ResolveUDPAddr("udp", ipPortStr)
++			if err != nil {
++				logf("error resolving UDP target %v: %v", ipPortStr, err)
++				c.Close()
++				return
++			}
++			localConn, err := net.DialUDP("udp", nil, addr)
++			if err != nil {
++				logf("error proxying UDP to %v: %v", ipPortStr, err)
++				c.Close()
++				return
++			}
++			tailcat.ProxyPacketConns(c, localConn)
++		}
++	}
++
+ 	if services.Contains("exit-node") {
+ 		s.OnTCPForward = func(dst netip.AddrPort) (handler func(net.Conn)) {
+ 			return tcpForwardTo(dst.String())
+@@ -1387,6 +1418,15 @@ func server(logf logger.Logf, serveSpec string) {
+ 		return tcpForwardTo(fmt.Sprintf("localhost:%v", port))
+ 	}
+ 
++	if len(udpPortSet) != 0 {
++		s.OnUDP = func(port uint16) (handler func(tailcat.ConnPacketConn)) {
++			if !udpPortSet.Contains(port) {
++				return nil
++			}
++			return udpForwardTo(fmt.Sprintf("127.0.0.1:%v", port))
++		}
++	}
++
+ 	if err := s.Start(); err != nil {
+ 		log.Fatalf("Server.Start: %v", err)
+ 	}
+diff --git a/cmd/tailcat/tailcat.go b/cmd/tailcat/tailcat.go
+--- a/cmd/tailcat/tailcat.go
++++ b/cmd/tailcat/tailcat.go
+@@ -416,6 +416,9 @@ The arguments are port numbers, port ranges, and service names,
+ either as separate arguments or comma-separated. Ports are proxied
+ to the same port on localhost. Service names are:
+ 
++The --udp flag separately selects UDP ports or ranges to proxy to the
++same ports on localhost. UDP is opt-in and does not change TCP serving.
++
+ 	all          serve all ports
+ 	exit-node    run an exit node for all addresses
+ 	ssh          SSH server requiring a public key listed by
+@@ -439,6 +442,10 @@ Serve some ports:
+ 
+ 	tailcat serve 22,80,443,8000-8999
+ 
++Serve UDP port 53 while also serving TCP port 8080:
++
++	tailcat serve --udp=53 8080
++
+ Serve all ports:
+ 
+ 	tailcat serve all

{tailkitty-0.2.2 → tailkitty-0.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tailkitty"
-version = "0.2.2"
+version = "0.2.3"
 description = "Python tooling and a verified distribution for Tailscale Tailcat"
 readme = "README.md"
 requires-python = ">=3.11"

{tailkitty-0.2.2 → tailkitty-0.2.3}/scripts/smoke_wheel.py

@@ -15,6 +15,41 @@ from pathlib import Path
 
 from .targets import host_target
 
+UDP_SMOKE = r"""import socket
+import threading
+
+from tailkitty import Client, ServerProcess
+
+sock = socket.socket(type=socket.SOCK_DGRAM)
+sock.settimeout(5)
+sock.bind(("127.0.0.1", 0))
+port = sock.getsockname()[1]
+
+def echo():
+    data, source = sock.recvfrom(2048)
+    sock.sendto(data, source)
+
+thread = threading.Thread(target=echo, daemon=True)
+thread.start()
+try:
+    server = ServerProcess(
+        key="new",
+        udp=port,
+        env={"TS_DEBUG_TAILCAT_LOCAL_DERP": "1"},
+    )
+    try:
+        server.start(timeout=5)
+        with Client(server.token).connect_udp(port, timeout=5) as connection:
+            response = connection.request(b"tailkitty-udp-smoke", timeout=3)
+            assert response.data == b"tailkitty-udp-smoke"
+    finally:
+        server.stop(grace_period=2)
+    thread.join(timeout=1)
+    assert not thread.is_alive()
+finally:
+    sock.close()
+"""
+
 
 def smoke_data_plane(backend: Path) -> None:
     """Prove the bundled helper can complete a real encrypted peer handshake."""
@@ -86,12 +121,19 @@ def smoke_wheel(wheel: Path, *, uv: str = "uv") -> dict[str, object]:
             raise RuntimeError("installed wheel did not discover its verified host bundle")
         backend = Path(report["backend"]["path"])
         smoke_data_plane(backend)
+        subprocess.run(
+            [str(interpreter), "-c", UDP_SMOKE],
+            cwd=root,
+            check=True,
+            timeout=15,
+        )
         return {
             "wheel": wheel.name,
             "target": target.name,
             "backend": report["backend"]["path"],
             "tailcat_version": bundle["tailcat_version"],
             "data_plane": "verified",
+            "udp_data_plane": "verified",
             "verified": bundle["verified"],
         }
 

{tailkitty-0.2.2 → tailkitty-0.2.3}/src/tailkitty/__init__.py

@@ -12,16 +12,20 @@ from .destination import DestinationError, resolve_destination, resolve_destinat
 from .diagnostics import diagnostics
 from .process import AsyncServerProcess, ServerProcess, ServerStartError, run_async, send
 from .token import ConnInfo, DerpNode, DerpRegion, TokenError, parse_token, resolve_token
+from .udp import MAX_UDP_PAYLOAD, AsyncUDPConnection, Datagram, UDPConnection, UDPError
 
 __all__ = [
+    "MAX_UDP_PAYLOAD",
     "AsyncClient",
     "AsyncServerProcess",
+    "AsyncUDPConnection",
     "BackendInfo",
     "BackendNotFound",
     "BundleError",
     "BundleManifest",
     "Client",
     "ConnInfo",
+    "Datagram",
     "DerpMapCache",
     "DerpMapError",
     "DerpNode",
@@ -30,6 +34,8 @@ __all__ = [
     "ServerProcess",
     "ServerStartError",
     "TokenError",
+    "UDPConnection",
+    "UDPError",
     "diagnostics",
     "inspect_backend",
     "parse_token",