refactor(io): replace Data with byte-oriented APIs#492
Draft
DzmingLi wants to merge 1 commit into
Draft
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
@io.DataabstractionReader::read_allreturn ownedBytesWriter::writeacceptBytesViewread_all_text,read_all_json,write_text, andwrite_jsonBytes/BytesViewthrough the publicfs,http, andprocessAPIs and migrate the repositoryWriter::write_onceprogress and reject zero-capacityBufferedWriters instead of allowing an infinite write loopMotivation
Datacurrently serves two unrelated roles:Bytes, strings, and JSON; andread_all, even though that result always containsBytes.The implementation calls this a hack itself. It also obscures ownership and allocation: receiving raw bytes is represented as
&Data, while.text()and.json()can repeat conversions. Copying that shape into a synchronous I/O package would create another trait-object boundary instead of giving sync and async I/O the same byte-oriented core.This draft makes the stream boundary explicit: raw I/O uses
BytesViewfor input and ownedBytesfor collected output. Text and JSON conversion remain convenient, but are named operations.API migration
writer.write(bytes)writer.write(bytes)writer.write("text")writer.write_text("text")writer.write(json)writer.write_json(json)reader.read_all().binary()reader.read_all()reader.read_all().text()reader.read_all_text()reader.read_all().json()reader.read_all_json()If an old
&Dataresult was saved and converted later, save the returnedBytesinstead and call@utf8.decode/@json.parseexplicitly. Do not replace multiple conversions with multipleread_all_*calls: each helper drains the reader.Related public changes:
fs.read_filereturnsBytes;fs.write_fileacceptsBytesViewBytesView; collected bodies returnBytescollect_*helpers returnBytesThis is an intentional breaking change. It also affects external
Reader/Writerimplementations and callers that previously passed strings or JSON directly to high-level byte-body APIs.Design points for review
writeremains the byte operationThis draft intentionally uses
Writer::write(BytesView). GenericShowformatting belongs on a text sink/logger or behind an explicit text adapter, rather than occupying the primary binary I/O operation.This supersedes only the
Writer::write_datarename direction in #386. The independentOutput::write_stringchange from that PR is not included here.HTTP string interpolation
ServerConnection::write_string_interpolationchanges from&@io.Datato&Show, matching ordinary string-interpolation display semantics. This is not mechanically equivalent forBytesorJson: callers that want raw bytes or JSON wire format must usewriteorwrite_jsonexplicitly. This behavior is called out for discussion rather than presented as compatibility-preserving.