qubit_fs/spi/
opened_async_directory_stream.rs

1// =============================================================================
2//    Copyright (c) 2026 Haixing Hu.
3//
4//    SPDX-License-Identifier: Apache-2.0
5//
6//    Licensed under the Apache License, Version 2.0.
7// =============================================================================
8// facade.
9//! Provider-opened asynchronous directory stream envelope.
10
11use super::AsyncDirectoryStreamSession;
12use crate::directory::AsyncDirectoryStream;
13use crate::directory::ListOptions;
14use crate::directory::ListScope;
15use crate::metadata::FileSystemLimits;
16use crate::path::PathSemantics;
17
18/// An already-open asynchronous directory stream.
19///
20/// # Examples
21///
22/// ```rust
23/// use qubit_fs::error::FsResult;
24/// use qubit_fs::metadata::DirEntry;
25/// use qubit_fs::spi::{AsyncDirectoryStreamSession, OpenedAsyncDirectoryStream, SpiFuture};
26///
27/// struct EmptyStream;
28/// impl AsyncDirectoryStreamSession for EmptyStream {
29///     fn next_entry_async(&mut self) -> SpiFuture<'_, FsResult<Option<DirEntry>>> {
30///         Box::pin(async { Ok(None) })
31///     }
32/// }
33/// let _stream = OpenedAsyncDirectoryStream::new(Box::new(EmptyStream));
34/// ```
35pub struct OpenedAsyncDirectoryStream {
36    /// Provider enumeration session awaiting facade validation.
37    session: Box<dyn AsyncDirectoryStreamSession>,
38}
39
40impl OpenedAsyncDirectoryStream {
41    /// Wraps an opened provider directory-enumeration session.
42    ///
43    /// # Parameters
44    /// - `session`: Provider enumeration session.
45    ///
46    /// # Returns
47    /// An opened asynchronous stream envelope for facade validation.
48    #[inline]
49    #[must_use]
50    pub fn new(session: Box<dyn AsyncDirectoryStreamSession>) -> Self {
51        Self { session }
52    }
53
54    /// Transfers the stream into the facade handle.
55    ///
56    /// # Parameters
57    /// - `root`: Validated directory root requested by the caller.
58    /// - `options`: Validated listing behavior.
59    /// - `provider`: Stable provider identifier used in generated errors.
60    ///
61    /// # Returns
62    /// A facade-owned asynchronous directory stream.
63    #[inline]
64    pub(crate) fn into_stream(
65        self,
66        scope: ListScope,
67        options: ListOptions,
68        provider: &str,
69        path_semantics: PathSemantics,
70        limits: FileSystemLimits,
71    ) -> crate::error::FsResult<AsyncDirectoryStream> {
72        AsyncDirectoryStream::new(scope, self.session, options, provider, path_semantics, limits)
73    }
74}
qubit_fs/spi/opened_async_directory_stream.rs

qubit_fs/spi/
opened_async_directory_stream.rs
