qubit_redact/facade/redactor/
process.rs

1// =============================================================================
2//    Copyright (c) 2025 - 2026 Haixing Hu.
3//
4//    SPDX-License-Identifier: Apache-2.0
5//
6//    Licensed under the Apache License, Version 2.0.
7// =============================================================================
8//! Process, argument-vector, and environment redaction operations.
9
10use std::ffi::OsStr;
11
12use super::Redactor;
13use crate::RedactionInspection;
14use crate::RedactionInspectionError;
15use crate::RedactionTextOutput;
16
17impl Redactor {
18    /// Redacts an argument vector through one completed text transaction.
19    #[must_use]
20    pub fn redact_argv<'items, I>(&self, items: I) -> RedactionTextOutput
21    where
22        I: IntoIterator<Item = crate::formats::argv::ArgvItem<'items>>,
23    {
24        let mut session = self.text_runtime();
25        session.argv(|argv| {
26            let _ = argv.items(items);
27        });
28        session.finish()
29    }
30
31    /// Inspects explicitly classified argv items without rendering them.
32    ///
33    /// # Errors
34    ///
35    /// Returns [`RedactionInspectionError`] when non-UTF-8 data or a shared
36    /// resource limit prevents complete inspection.
37    pub fn inspect_argv<'items, I>(&self, items: I) -> Result<RedactionInspection, RedactionInspectionError>
38    where
39        I: IntoIterator<Item = crate::formats::argv::ArgvItem<'items>>,
40    {
41        let mut session = self.inspection_runtime();
42        crate::formats::argv::inspection::inspect_items(&mut session, items, false);
43        session.finish()
44    }
45
46    /// Redacts argv items using heuristic option classification.
47    #[must_use]
48    pub fn redact_heuristic_argv<'items, I>(&self, items: I) -> RedactionTextOutput
49    where
50        I: IntoIterator<Item = crate::formats::argv::ArgvItem<'items>>,
51    {
52        let mut session = self.text_runtime();
53        session.argv(|argv| {
54            let _ = argv.heuristic_items(items);
55        });
56        session.finish()
57    }
58
59    /// Inspects argv items using heuristic option classification.
60    ///
61    /// # Errors
62    ///
63    /// Returns [`RedactionInspectionError`] when non-UTF-8 data, incomplete
64    /// option syntax, or a shared resource limit prevents complete inspection.
65    pub fn inspect_heuristic_argv<'items, I>(&self, items: I) -> Result<RedactionInspection, RedactionInspectionError>
66    where
67        I: IntoIterator<Item = crate::formats::argv::ArgvItem<'items>>,
68    {
69        let mut session = self.inspection_runtime();
70        crate::formats::argv::inspection::inspect_items(&mut session, items, true);
71        session.finish()
72    }
73
74    /// Redacts one environment assignment through one completed transaction.
75    #[must_use]
76    pub fn redact_env(&self, name: &str, value: &str) -> RedactionTextOutput {
77        let mut session = self.text_runtime();
78        session.env(|environment| {
79            let _ = environment.pair(name, value);
80        });
81        session.finish()
82    }
83
84    /// Inspects one environment assignment without rendering it.
85    ///
86    /// # Errors
87    ///
88    /// Returns [`RedactionInspectionError`] when the shared input or
89    /// structural budget prevents complete inspection.
90    pub fn inspect_env(&self, name: &str, value: &str) -> Result<RedactionInspection, RedactionInspectionError> {
91        let mut session = self.inspection_runtime();
92        crate::formats::env::inspection::inspect_pair(&mut session, name, value);
93        session.finish()
94    }
95
96    /// Redacts environment assignments through one completed transaction.
97    #[must_use]
98    pub fn redact_env_pairs<'items, I>(&self, pairs: I) -> RedactionTextOutput
99    where
100        I: IntoIterator<Item = (&'items OsStr, &'items OsStr)>,
101    {
102        let mut session = self.text_runtime();
103        session.env(|environment| {
104            let _ = environment.os_pairs(pairs);
105        });
106        session.finish()
107    }
108
109    /// Inspects environment assignments without rendering them.
110    ///
111    /// # Errors
112    ///
113    /// Returns [`RedactionInspectionError`] when non-UTF-8 data or a shared
114    /// resource limit prevents complete inspection.
115    pub fn inspect_env_pairs<'items, I>(&self, pairs: I) -> Result<RedactionInspection, RedactionInspectionError>
116    where
117        I: IntoIterator<Item = (&'items OsStr, &'items OsStr)>,
118    {
119        let mut session = self.inspection_runtime();
120        crate::formats::env::inspection::inspect_os_pairs(&mut session, pairs);
121        session.finish()
122    }
123
124    /// Redacts one process command through one completed text transaction.
125    #[must_use]
126    pub fn redact_process<'arguments, 'variables, A, E>(
127        &self,
128        program: &'arguments OsStr,
129        arguments: A,
130        variables: E,
131    ) -> RedactionTextOutput
132    where
133        A: IntoIterator<Item = crate::formats::argv::ArgvItem<'arguments>>,
134        E: IntoIterator<Item = (&'variables OsStr, &'variables OsStr)>,
135    {
136        let mut session = self.text_runtime();
137        let _ = session.process(|process| {
138            let _ = process.command(program, arguments, variables);
139        });
140        session.finish()
141    }
142
143    /// Inspects one process command without rendering its components.
144    ///
145    /// # Errors
146    ///
147    /// Returns [`RedactionInspectionError`] when argv or environment data is
148    /// invalid, incomplete, or rejected by a shared resource limit.
149    pub fn inspect_process<'arguments, 'variables, A, E>(
150        &self,
151        program: &'arguments OsStr,
152        arguments: A,
153        variables: E,
154    ) -> Result<RedactionInspection, RedactionInspectionError>
155    where
156        A: IntoIterator<Item = crate::formats::argv::ArgvItem<'arguments>>,
157        E: IntoIterator<Item = (&'variables OsStr, &'variables OsStr)>,
158    {
159        let mut session = self.inspection_runtime();
160        let command = std::iter::once(crate::formats::argv::ArgvItem::plain(program)).chain(arguments);
161        crate::formats::argv::inspection::inspect_items(&mut session, command, true);
162        crate::formats::env::inspection::inspect_os_pairs(&mut session, variables);
163        session.finish()
164    }
165}
qubit_redact/facade/redactor/process.rs

qubit_redact/facade/redactor/
process.rs
