Crate conpty_oxide 

Correctness-first Windows ConPTY (pseudoconsole) library.

conpty-oxide wraps the Windows pseudoconsole (ConPTY) API with a focus on getting the hard parts right:

• A well-defined EOF contract for the console output pipe.
• No hangs around ClosePseudoConsole.
• Reliable process-tree termination (“kill tree”) via Job objects.
• A blocking API (default blocking feature) and an async API behind the tokio feature.
• Dynamic loading of conpty.dll, falling back to the system console API.

This crate targets Windows exclusively and does not compile on other platforms.

Low-level lifecycle types, backend identity, and unchecked bundle loading are intentionally not part of the 0.1 contract. Errors are opaque — there are no variants to match — and Result always uses this crate’s error. Hidden compile-fail doctests pin each of these boundaries.

Where to start

blocking holds the synchronous API. Start a managed session with blocking::Command::spawn, then choose blocking::Session::wait when output is unnecessary, blocking::Session::collect_output to retain raw VT, or blocking::Session::into_parts for independently owned I/O, child, and control handles.

The tokio module mirrors all three paths with AsyncRead/AsyncWrite streams and registered process waits. Frontend types never change meaning based on the selected feature: choose blocking or tokio explicitly.

Feature flags

• blocking (default) — the synchronous frontend.
• tokio — the asynchronous frontend on Tokio.
• tracing — diagnostics through the tracing crate; never changes the public API or any behavior.

The features can be combined.

Managed sessions

A managed session is bounded by its root process. Once the root’s real exit status is saved, descendants remaining in the session Job are terminated and the output tail proceeds to EOF. Splitting with into_parts changes ownership only; it does not detach the process tree.

Input drop or shutdown ends the terminal session rather than delivering an ordinary stdin EOF. Output is one raw UTF-8/VT byte stream with no separate stdout and stderr channels. collect_output retains an unbounded amount of output; use wait to discard it safely or owned parts to stream it.

Choosing a ConPTY implementation

Automatic selection needs no setup: it prefers a validated standalone conpty.dll bundle next to the executable, then falls back to the operating system’s ConPTY. An application can also select a bundle explicitly to get the newer console host’s behaviour on older Windows versions:

• ConPtyBackend::auto uses a valid bundle found next to the executable, falls back to the system implementation when that bundle is rejected, and returns an error if neither is usable. This is also what the default backend selection does.
• ConPtyBackend::from_dir loads a bundle from a directory you name, validating that its conpty.dll and OpenConsole.exe are a matching pair before either runs.
• With either frontend enabled, SessionOptions::backend selects a backend for a managed session.

Cursor inheritance, manual EOF policy, detached sessions, and pre-staged spawning are intentionally outside the 0.1 API. They can be added later as typed advanced operations when concrete use cases justify them.

Modules

blockingblocking

Blocking pseudoconsole sessions.

tokiotokio

Asynchronous pseudoconsole sessions, driven by Tokio.

Structs

BackendError

A failure while locating, loading, or validating a ConPTY backend.

ConPtyBackend

A loaded ConPTY implementation.

Error

A failure produced by conpty-oxide.

ExitStatus

The exit status of a child process that has terminated.

PtyControllerblocking or tokio

Cloneable control handle shared by both public front ends.

SessionOptionsblocking or tokio

Safe configuration for a managed pseudoconsole session.

SessionOutputblocking or tokio

Virtual-terminal output collected from a managed session.

Size

Dimensions of a pseudoconsole, in character cells.

Enums

BackendErrorKind

The failure class reported by a BackendError.

ErrorKind

The operation phase in which an Error occurred.

Type Aliases

Result

Convenience alias for results produced by this crate.