EXAMPLE-ARCH: platform-* driver tier and abi-buf crate pattern#3
Merged
Conversation
Two additions prompted by building out a mobile teleconferencing client on top of drv where the original doc left gaps: * A platform-* tier sitting below domain drivers in the Cargo graph, for primitives that multiple domain drivers actively call into (UDP, HTTP, timers, keychain). Cross-driver imports into these are expected; the isolation rule in guideline 8 is carved out for them. Criterion is "called by multiple domain drivers," not "wraps a platform API" — observed-by-many singletons like lifecycle stay as regular driver-*. * A Crossing the ABI section covering foreign-owned byte buffers across Rust -> Swift / Kotlin. Arc<[u8]> picked over Arc<Vec<u8>> and bytes::Bytes, with the RustBuf / NativeBuf handoff pattern and the ownership invariant spelled out. Kept in its own abi-* tier separate from drivers since this is type contracts, not behaviour. Two new guidelines (13, 14) codify both; guideline 8 gains a one-paragraph exception note pointing at 13. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Which ref-counted byte container (Arc<[u8]>, Bytes, Vec<u8>, ...) an application chooses is situation-specific — driven by what upstream libraries hand over and whether slicing is in the hot path. Not a design-doc decision. Replace the prescriptive "pick Arc<[u8]>" subsection with a short "picking a container" paragraph that acknowledges the choice exists without taking one. The Rust -> native handoff code example still uses Arc<[u8]> but now explicitly as a concrete illustration rather than a recommendation. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The rest of the document works at an architectural-pattern level with sparing code examples and almost no platform-API name-dropping. The new ABI section was written at tutorial level — RustBuf struct + impl + extern fn, plus specific Swift/Kotlin API calls (Data(bytesNoCopy:...), NewDirectByteBuffer, withUnsafeBytes, etc.). Out of tone. Cut the code block, the per-platform API names, the subsection headers, and the inline crates/abi-buf tree (already in the master crate layout). What remains: one paragraph stating the concern, a two-bullet summary of the two directions (Rust-owned vs foreign-owned), and a closing paragraph on what the layer doesn't cover (GPU-typed opaque buffers). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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
2 participants
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
Two additions to
EXAMPLE-ARCH.mdprompted by building a mobile (iOS + Android) teleconferencing client on top of drv and hitting questions the doc didn't already answer.1.
platform-*driver tier. Shared primitives — UDP, HTTP, timers, keychain — that multiple domain drivers call into. Sit below domain drivers in the Cargo graph; cross-driver imports into them are expected. Three-tier dep rule added (state-*→platform-*→driver-*→runtime). Guideline 8 gains a one-paragraph exception pointing at the new guideline 13.Careful about the promotion criterion: called by multiple domain drivers, not wraps a platform API and not observed by many parts of the app. Singleton event-observed drivers (lifecycle, foreground/background) stay as regular
driver-*even when cross-cutting.2.
Crossing the ABI: foreign-owned buffers. New top-level section covering Rust ↔ Swift / Kotlin byte-buffer ownership — the thing the original doc's terminal-editor example didn't hit. PicksArc<[u8]>overArc<Vec<u8>>/bytes::Byteswith reasoning, gives theRustBuf+rust_buf_freepattern for Rust → native, notes that native → Rust usually needs no refcount because the borrow is call-scoped, and carves out platform-typed GPU buffers (CVPixelBuffer,HardwareBuffer) as needing their own per-driver ABI rather than fitting inabi-buf. New guideline 14 codifies theabi-*crate prefix.TOC renumbered (section 9 inserted; old 9→10, etc.). No existing guidelines removed or renumbered.
Test plan
🤖 Generated with Claude Code