[FEATURE] Complete generation-bound directory streams #82

Open
opened 2026-11-07 18:21:28 +01:00 by erikinkinen · 0 comments
Owner

Problem and motivation

Directory iteration currently exposes raw descriptor operations. A directory stream must keep its entry, cursor and close operations tied to the original binding, even if another caller closes the descriptor or reuses its number.

Proposed behavior and scope

Add caller-owned, namespaced C and safe Rust directory streams over the existing mediated directory interface. Supply opening/adoption, counted entry reads, descriptor observation, saved positions, seeking, rewinding and close. Keep caller-selected name storage and complete raw names rather than imposing NAME_MAX or an allocator.

Compatibility 1.34 adds directory identity observation and qualified operations. Identity includes the original descriptor-row and description-row coordinates and both generations. Existing raw descriptor interfaces remain available. Conventional POSIX aliases remain a separate libc startup and signal integration requirement.

Authority, security and reliability

The original authenticated Posixd client and its live descriptor table supply authority. Identity words grant no access or retained reference. Validate every coordinate against actual process-bound rows before acquiring the original per-call description hold. Close or replacement, including an alias of the same description, makes the old stream stale. Its operations must return EBADF without affecting the replacement.

Keep complete native request, reply and caller custody through retirement. EOF remains distinct from errno. Never retry an operation whose cursor or close effect is uncertain. Retain uncertainty through the original terminal cleanup path. A stream borrows no filesystem-provider route and introduces no persistent native lease or global stream lock.

Acceptance criteria

  • Implement and document the qualified wire family, preserving raw descriptor interfaces.
  • Validate exact process, descriptor and description identity before effects and original hold admission.
  • Supply complete caller-owned C/Rust stream and counted-entry interfaces with explicit lifetime and teardown behavior.
  • Reject stale, closed, wrong-client, wrong-type and malformed identities; cover close/reuse and replacement by an alias of the same description.
  • Preserve EOF/error separation, output atomicity, complete names, saved positions and shared cursor behavior.
  • Adopt the stream in the original native C/Rust filesystem workload and preserve earlier descriptor and cleanup checks.
  • Update component and manual contracts and run the relevant unit, native, VM and warning-denied component checks.

Alternatives and tradeoffs

Retaining only an fd number can redirect work to a replacement. A self-address or saved-position cookie does not establish original custody. Persistent native stream leases would require extra arena storage and process-terminal cleanup; generation-qualified admission supplies the required stale-on-external-close contract without that extra authority lifetime.

Tracking and rollout

Build on mediated directory iteration and mediated file operations. Land the ABI, mediator, C/Rust runtime and native consumer as one coherent source cohort. Track completion through the phase tracker.

## Problem and motivation Directory iteration currently exposes raw descriptor operations. A directory stream must keep its entry, cursor and close operations tied to the original binding, even if another caller closes the descriptor or reuses its number. ## Proposed behavior and scope Add caller-owned, namespaced C and safe Rust directory streams over the existing mediated directory interface. Supply opening/adoption, counted entry reads, descriptor observation, saved positions, seeking, rewinding and close. Keep caller-selected name storage and complete raw names rather than imposing NAME_MAX or an allocator. Compatibility 1.34 adds directory identity observation and qualified operations. Identity includes the original descriptor-row and description-row coordinates and both generations. Existing raw descriptor interfaces remain available. Conventional POSIX aliases remain a separate libc startup and signal integration requirement. ## Authority, security and reliability The original authenticated Posixd client and its live descriptor table supply authority. Identity words grant no access or retained reference. Validate every coordinate against actual process-bound rows before acquiring the original per-call description hold. Close or replacement, including an alias of the same description, makes the old stream stale. Its operations must return EBADF without affecting the replacement. Keep complete native request, reply and caller custody through retirement. EOF remains distinct from errno. Never retry an operation whose cursor or close effect is uncertain. Retain uncertainty through the original terminal cleanup path. A stream borrows no filesystem-provider route and introduces no persistent native lease or global stream lock. ## Acceptance criteria - [ ] Implement and document the qualified wire family, preserving raw descriptor interfaces. - [ ] Validate exact process, descriptor and description identity before effects and original hold admission. - [ ] Supply complete caller-owned C/Rust stream and counted-entry interfaces with explicit lifetime and teardown behavior. - [ ] Reject stale, closed, wrong-client, wrong-type and malformed identities; cover close/reuse and replacement by an alias of the same description. - [ ] Preserve EOF/error separation, output atomicity, complete names, saved positions and shared cursor behavior. - [ ] Adopt the stream in the original native C/Rust filesystem workload and preserve earlier descriptor and cleanup checks. - [ ] Update component and manual contracts and run the relevant unit, native, VM and warning-denied component checks. ## Alternatives and tradeoffs Retaining only an fd number can redirect work to a replacement. A self-address or saved-position cookie does not establish original custody. Persistent native stream leases would require extra arena storage and process-terminal cleanup; generation-qualified admission supplies the required stale-on-external-close contract without that extra authority lifetime. ## Tracking and rollout Build on [mediated directory iteration](https://git.erikinkinen.fi/erix/lib-cstd/issues/15) and [mediated file operations](https://git.erikinkinen.fi/erix/lib-cstd/issues/14). Land the ABI, mediator, C/Rust runtime and native consumer as one coherent source cohort. Track completion through the [phase tracker](https://git.erikinkinen.fi/erix/integration/issues/65).
erikinkinen added this to the Alpha 1 milestone 2026-11-07 18:21:28 +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#82
No description provided.