[FEATURE] Add mediated directory stream adapters #15

Open
opened 2026-10-27 20:08:17 +01:00 by erikinkinen · 1 comment
Owner

Problem and motivation

The mediator already supports directory iteration, but the C runtime cannot use it through its retained realm binding. Build tools need complete raw names, end-of-directory results and cursor operations without acquiring filesystem-provider authority.

Proposed behavior and scope

Add typed Rust requests and namespaced C interfaces for reading one directory entry, reporting its cookie, seeking and rewinding. Use the existing compatibility messages and the same independently retained call storage as other mediated file operations.

Reading returns one complete entry or EOF into caller-owned storage. Preserve raw name bytes and reject insufficient capacity without truncation. Cookies remain opaque values belonging to the original directory description. Conventional DIR interfaces and aliases remain part of the broader libc adoption work.

Authority, security and reliability

Only the original Posixd realm binding supplies transport authority. Descriptor numbers and cookies do not grant access. Keep borrowed buffers and call state alive through native completion and retirement; retain uncertain calls and their first error. Do not retry a request whose cursor effect is unknown or create direct provider and host-OS fallback routes.

Acceptance criteria

  • Implement typed Rust and namespaced C read, tell, seek and rewind adapters with distinct entry, EOF and error results.
  • Connect the actual heap-client backend to the existing directory messages, with complete reply correlation and native retirement before buffer publication.
  • Cover raw names, exact and insufficient capacities, EOF, malformed replies, stale descriptors and cookies, interruption and cleanup failures with independent controls.
  • Add the C workload and its native integration oracle while preserving the existing realm and file-operation checks.
  • Update headers, symbol policies, inline documentation, component contracts and the technical manual; regenerate matching API references.
  • Complete strict component checks and the bounded native workload.

Alternatives and tradeoffs

Direct filesystem access would expose authority that these clients do not need. A fixed-size name array would impose an avoidable limit. Caller-owned storage fits the existing counted wire format and makes insufficient capacity explicit; a future conventional directory-stream wrapper can build on this interface.

Tracking and rollout

Part of the Phase 6 tracker, alongside the mediated file adapters. Land the runtime interface and backend together, then enroll the native consumer and generated references.

## Problem and motivation The mediator already supports directory iteration, but the C runtime cannot use it through its retained realm binding. Build tools need complete raw names, end-of-directory results and cursor operations without acquiring filesystem-provider authority. ## Proposed behavior and scope Add typed Rust requests and namespaced C interfaces for reading one directory entry, reporting its cookie, seeking and rewinding. Use the existing compatibility messages and the same independently retained call storage as other mediated file operations. Reading returns one complete entry or EOF into caller-owned storage. Preserve raw name bytes and reject insufficient capacity without truncation. Cookies remain opaque values belonging to the original directory description. Conventional DIR interfaces and aliases remain part of the broader libc adoption work. ## Authority, security and reliability Only the original Posixd realm binding supplies transport authority. Descriptor numbers and cookies do not grant access. Keep borrowed buffers and call state alive through native completion and retirement; retain uncertain calls and their first error. Do not retry a request whose cursor effect is unknown or create direct provider and host-OS fallback routes. ## Acceptance criteria - [x] Implement typed Rust and namespaced C read, tell, seek and rewind adapters with distinct entry, EOF and error results. - [x] Connect the actual heap-client backend to the existing directory messages, with complete reply correlation and native retirement before buffer publication. - [ ] Cover raw names, exact and insufficient capacities, EOF, malformed replies, stale descriptors and cookies, interruption and cleanup failures with independent controls. - [x] Add the C workload and its native integration oracle while preserving the existing realm and file-operation checks. - [ ] Update headers, symbol policies, inline documentation, component contracts and the technical manual; regenerate matching API references. - [ ] Complete strict component checks and the bounded native workload. ## Alternatives and tradeoffs Direct filesystem access would expose authority that these clients do not need. A fixed-size name array would impose an avoidable limit. Caller-owned storage fits the existing counted wire format and makes insufficient capacity explicit; a future conventional directory-stream wrapper can build on this interface. ## Tracking and rollout Part of the [Phase 6 tracker](https://git.erikinkinen.fi/erix/integration/issues/65), alongside the [mediated file adapters](https://git.erikinkinen.fi/erix/lib-cstd/issues/14). Land the runtime interface and backend together, then enroll the native consumer and generated references.
Author
Owner

Directory read, tell, seek and rewind are implemented in the C/Rust runtime and heap-client backend. They preserve whole raw names, EOF and shared-description cookies through the retained realm. Packaging, the C workload and manual section are included; matching API references and native workload acceptance remain open.

Directory read, tell, seek and rewind are implemented in the [C/Rust runtime](https://git.erikinkinen.fi/erix/lib-cstd/commit/2c7edd50c116e0176ff8ac49748db8a4998fbcf8) and [heap-client backend](https://git.erikinkinen.fi/erix/posixd/commit/2af5ce7bb9b02acf5912d2e93abadee1f7347116). They preserve whole raw names, EOF and shared-description cookies through the retained realm. [Packaging](https://git.erikinkinen.fi/erix/integration/commit/21c84469a6d393ceff0f706d5c2f64deced41495), the C workload and [manual section](https://git.erikinkinen.fi/erix/docs/commit/393dccb992759f1f081ff80ecdae47a7d18a8aa3) are included; matching API references and native workload acceptance remain open.
erikinkinen added this to the Alpha 1 milestone 2026-10-30 09:34:40 +01:00
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
erix/lib-cstd#15
No description provided.