From 6d2c5366dac1fe01320053a295cea5faa5b4a66b Mon Sep 17 00:00:00 2001 From: Martin Tomka Date: Thu, 6 Aug 2026 16:04:54 +0200 Subject: [PATCH 1/2] docs(bytesbuf_io): add stabilization notes Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 95a89ae9-292f-4300-878a-ac61ade1eb7b --- crates/bytesbuf_io/docs/DESIGN.md | 0 crates/bytesbuf_io/docs/STABILIZATION.md | 70 ++++++++++++++++++++++++ 2 files changed, 70 insertions(+) create mode 100644 crates/bytesbuf_io/docs/DESIGN.md create mode 100644 crates/bytesbuf_io/docs/STABILIZATION.md diff --git a/crates/bytesbuf_io/docs/DESIGN.md b/crates/bytesbuf_io/docs/DESIGN.md new file mode 100644 index 000000000..e69de29bb diff --git a/crates/bytesbuf_io/docs/STABILIZATION.md b/crates/bytesbuf_io/docs/STABILIZATION.md new file mode 100644 index 000000000..0a784ef2a --- /dev/null +++ b/crates/bytesbuf_io/docs/STABILIZATION.md @@ -0,0 +1,70 @@ +# Stabilization Notes + +These notes capture the pending decisions for stabilizing `bytesbuf_io`. They +describe proposals under review, not a finalized stable API. + +## Proposed stable boundary + +- Keep owned buffers as the fundamental I/O abstraction. Native asynchronous I/O + may retain memory for the entire operation, which cannot be represented safely by + an API based only on borrowed slices. +- Stabilize the core `Read` and `Write` traits after their required methods and + result types have been reviewed. +- Allow stable downstream crates to expose approved `bytesbuf_io` types in their + public APIs. + +Extension traits, test utilities, ecosystem adapters, and other convenience APIs +should remain outside the stable boundary until each surface is reviewed separately. + +## Trait requirements + +Review each current trait requirement instead of carrying it into the stable API by +default: + +- Remove `HasMemory`, `Memory`, and `Debug` supertraits where they are not essential + to the I/O contract. Memory providers can be exposed through separate capabilities + or adapters when an implementation benefits from endpoint-specific allocation. +- Decide whether `Send` is required by the traits, by each returned future, or only + at usage sites. The stable contract should not impose cross-thread execution when + an implementation and its caller are both thread-local. +- Select the concrete error boundary. The associated error type and the crate's + general-purpose `Error` wrapper must provide predictable composition without + exposing unstable implementation details. + +## Read and write operations + +The current read surface includes bounded reads, implementation-selected reads, and +allocation of a new buffer. Review which operations are fundamental and which can be +implemented as extensions without losing endpoint-specific efficiency. + +The `(usize, BytesBuf)` read result communicates both progress and ownership but is +easy to use incorrectly. Consider an intentional result type that names the bytes +read and returned buffer while preserving efficient ownership transfer. + +The write contract should continue to make full writes explicit. Partial-write, +flush, shutdown, cancellation, and end-of-stream semantics must be either defined by +the stable traits or explicitly left to adapters and endpoint-specific APIs. + +## Ecosystem adapters + +Borrowed-buffer APIs such as Tokio and `futures` I/O should be supported through +adapters rather than define the fundamental abstraction. Adapter documentation must +state when data is copied, when an allocation is required, and how cancellation +returns or releases an owned buffer. + +Dynamic or type-erased adapters should also be evaluated. Stabilization must account +for their allocation, dispatch, pinning, and error-erasure costs, as well as whether +they compose with both thread-local and `Send` implementations. + +## Pending review + +- [ ] Review the trait shape against `arty_io`, TCP, and fetch use cases. +- [ ] Explicitly list every API included in the stable surface. +- [ ] Resolve the `HasMemory`, `Memory`, and `Debug` supertrait requirements. +- [ ] Decide where `Send` requirements belong. +- [ ] Decide the stable I/O error representation. +- [ ] Confirm which read variants are fundamental. +- [ ] Decide whether read operations return a named result type. +- [ ] Define cancellation, end-of-stream, and partial-write semantics. +- [ ] Document compatibility adapters and their allocation and composition costs. +- [ ] Confirm stable signatures expose only approved stable types. From 5553dbe76ad715635e99f06279e071d92ab5e867 Mon Sep 17 00:00:00 2001 From: Martin Tomka Date: Thu, 6 Aug 2026 16:08:59 +0200 Subject: [PATCH 2/2] docs(bytesbuf_io): clarify current trait requirements Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 95a89ae9-292f-4300-878a-ac61ade1eb7b --- crates/bytesbuf_io/docs/STABILIZATION.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/crates/bytesbuf_io/docs/STABILIZATION.md b/crates/bytesbuf_io/docs/STABILIZATION.md index 0a784ef2a..1ba5b199c 100644 --- a/crates/bytesbuf_io/docs/STABILIZATION.md +++ b/crates/bytesbuf_io/docs/STABILIZATION.md @@ -18,15 +18,21 @@ should remain outside the stable boundary until each surface is reviewed separat ## Trait requirements -Review each current trait requirement instead of carrying it into the stable API by -default: +The current `Read` and `Write` traits unconditionally require `HasMemory`, `Memory`, +and `Debug`, and use `trait_variant` to require `Send` from implementations and +returned futures. Review each requirement instead of carrying it into the stable API +by default. Changing these requirements is a breaking API change that must be settled +before 1.0: - Remove `HasMemory`, `Memory`, and `Debug` supertraits where they are not essential to the I/O contract. Memory providers can be exposed through separate capabilities or adapters when an implementation benefits from endpoint-specific allocation. + Extension methods that currently rely on these inherited capabilities must be + adjusted as part of the same decision. - Decide whether `Send` is required by the traits, by each returned future, or only - at usage sites. The stable contract should not impose cross-thread execution when - an implementation and its caller are both thread-local. + at usage sites. Removing the current requirement changes guarantees available to + downstream callers. The stable contract should not impose cross-thread execution + when an implementation and its caller are both thread-local. - Select the concrete error boundary. The associated error type and the crate's general-purpose `Error` wrapper must provide predictable composition without exposing unstable implementation details.