psrp_rs/
lib.rs

1//! Async [MS-PSRP] client for Rust, built on top of [`winrm-rs`].
2//!
3//! `psrp-rs` implements the PowerShell Remoting Protocol on top of
4//! WS-Management. It reuses `winrm-rs` for transport, authentication and
5//! SOAP envelope handling, and layers the PSRP fragment/CLIXML protocol on
6//! top to deliver:
7//!
8//! - typed PowerShell objects on the `Output` stream;
9//! - isolated `Error`, `Warning`, `Verbose`, `Debug`, `Information` and
10//!   `Progress` streams;
11//! - a persistent [`RunspacePool`] that keeps a `powershell.exe` process
12//!   alive across many pipelines;
13//! - a builder-style [`Pipeline`] API.
14//!
15//! [MS-PSRP]: https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-psrp/
16//! [`winrm-rs`]: https://docs.rs/winrm-rs
17//!
18//! # Example
19//!
20//! ```no_run
21//! use psrp_rs::{RunspacePool, WinrmPsrpTransport};
22//! use winrm_rs::{AuthMethod, WinrmClient, WinrmConfig, WinrmCredentials};
23//!
24//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
25//! let client = WinrmClient::new(
26//!     WinrmConfig {
27//!         auth_method: AuthMethod::Ntlm,
28//!         ..Default::default()
29//!     },
30//!     WinrmCredentials::new("administrator", "Passw0rd!", ""),
31//! )?;
32//!
33//! let (rpid, creation) = RunspacePool::<WinrmPsrpTransport>::build_creation_fragments(1, 1)?;
34//! let transport = WinrmPsrpTransport::open(&client, "win-host.lab", &creation).await?;
35//! let mut pool = RunspacePool::open_from_transport(transport, rpid, 1, 1).await?;
36//!
37//! let objects = pool
38//!     .run_script("Get-Process | Select-Object -First 5 Name, Id")
39//!     .await?;
40//! for obj in objects {
41//!     println!("{obj:?}");
42//! }
43//!
44//! pool.close().await?;
45//! # Ok(())
46//! # }
47//! ```
48//!
49//! # Scope
50//!
51//! P0 covers: fragment/CLIXML primitives, opening a pool, running a script,
52//! collecting every standard stream. P1 extends to per-stream processing
53//! via the [`Pipeline`] builder (already available here) and a blocking
54//! wrapper in the [`blocking`] module. P2 items — `<Ref>`-based CLIXML
55//! round-tripping, pipeline input streaming, reconnect/disconnect — are
56//! still on the roadmap.
57
58#![forbid(unsafe_code)]
59#![warn(missing_debug_implementations)]
60
61pub mod blocking;
62pub mod clixml;
63pub mod crypto;
64pub mod error;
65pub mod fragment;
66pub mod host;
67pub mod message;
68pub mod metadata;
69pub mod pipeline;
70pub mod records;
71pub mod runspace;
72pub mod shared;
73#[cfg(feature = "ssh")]
74pub mod ssh;
75#[cfg(feature = "ssh")]
76pub use ssh::{SshAuth, SshConfig, SshPsrpTransport};
77pub mod transport;
78
79pub use clixml::{PsObject, PsValue, RefIdAllocator, parse_clixml, to_clixml};
80pub use crypto::{ClientSessionKey, SessionKey};
81pub use error::{PsrpError, Result};
82pub use host::{BufferedHost, HostCallKind, HostMethodId, NoInteractionHost, PsHost};
83pub use metadata::{CommandMetadata, CommandType, ParameterMetadata};
84pub use pipeline::{Argument, Command, Pipeline, PipelineHandle, PipelineResult, PipelineState};
85pub use records::{
86    ErrorCategoryInfo, ErrorRecord, ExceptionInfo, FromPsObject, InformationRecord, InvocationInfo,
87    ProgressRecord, TraceRecord, WarningRecord,
88};
89pub use runspace::{
90    DisconnectedPool, PROTOCOL_VERSION, RunspacePool, RunspacePoolState, RunspacePoolStateMachine,
91};
92pub use shared::SharedRunspacePool;
93pub use transport::{PsrpTransport, WinrmPsrpTransport};
94
95// Re-export the `winrm-rs` types commonly needed by callers so they
96// don't have to depend on `winrm-rs` directly.
97pub use winrm_rs::{AuthMethod, WinrmClient, WinrmConfig, WinrmCredentials, WinrmError};
psrp_rs/lib.rs

psrp_rs/
lib.rs
