podman_lens/
lib.rs

1//! Version-aware native Podman inspection and non-executing deployment planning.
2//!
3//! `PodmanLens` acquires one explicitly selected Libpod service through a replaceable transport,
4//! preserves typed native observation state and provenance, discovers an evidence-backed resource
5//! graph, plans caller-authored target intent, and renders deterministic CLI and Libpod
6//! descriptions. It never discovers an ambient endpoint, shells out to `podman` for input, sends a
7//! mutating acquisition request, or executes a rendered plan.
8//!
9//! # Explicit read-only acquisition
10//!
11//! The built-in Unix transport accepts one caller-supplied socket and rejects every method except
12//! `GET` before opening it. Environment values are redacted by default and secret payload endpoints
13//! are never requested.
14//!
15//! ```no_run
16//! # #[cfg(unix)]
17//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
18//! use podman_lens::{
19//!     AcquisitionOptions, DiscoveryRequest, ReadOnlyUnixTransport,
20//!     ReadOnlyUnixTransportTimeouts, TransportLimits, UnixConnection, acquire_inventory,
21//!     discover,
22//! };
23//!
24//! let transport = ReadOnlyUnixTransport::new(
25//!     UnixConnection::new("/run/user/1000/podman/podman.sock")?,
26//!     TransportLimits::default(),
27//!     ReadOnlyUnixTransportTimeouts::default(),
28//! )?;
29//! let runtime = tokio::runtime::Builder::new_current_thread().enable_all().build()?;
30//! let graph = runtime.block_on(async {
31//!     let inventory = acquire_inventory(&transport, AcquisitionOptions::redacted()).await?;
32//!     let mut request = DiscoveryRequest::new();
33//!     request.select_all();
34//!     discover(&inventory, &request)
35//! })?;
36//! assert!(graph.requested_roots().is_empty());
37//! # Ok(())
38//! # }
39//! ```
40//!
41//! `select_all` is retained separately on the graph; exact and label selectors are available when
42//! the caller needs a narrower application boundary. See the task-oriented public guides for
43//! selector, grouping, network-crossing, and privacy contracts.
44//!
45//! # Deterministic offline planning and rendering
46//!
47//! Planning uses explicit target-side intent and opens no connection. Rendering produces data and
48//! review text only.
49//!
50//! ```
51//! use podman_lens::{
52//!     DeploymentIntent, DeploymentResource, DeploymentResourceId, ImageIntent, ImagePullPolicy,
53//!     ImageSource, ObservedApiVersion, ObservedPodmanVersion, ResourceKind, TargetProfile,
54//!     artifact::deployment_v1, plan_deployment, render_deployment,
55//! };
56//!
57//! let target = TargetProfile::new(
58//!     ObservedPodmanVersion::parse("6.1.0")?,
59//!     ObservedApiVersion::parse("6.1.0")?,
60//! )?;
61//! let image = DeploymentResourceId::new(ResourceKind::Image, "application-image")?;
62//! let mut intent = DeploymentIntent::new(target);
63//! intent.add_resource(DeploymentResource::Image(ImageIntent::new(
64//!     image,
65//!     ImageSource::new("registry.example.invalid/team/application:1")?,
66//!     ImagePullPolicy::Missing,
67//! )?));
68//! let planned = plan_deployment(&intent);
69//! let plan = planned.plan().expect("reviewed intent produces a complete plan");
70//! let rendered = render_deployment(plan);
71//! let rendering = rendered.rendering().expect("reviewed target renders exactly");
72//! assert_eq!(plan.operations().len(), 1);
73//! assert_eq!(rendering.operations()[0].cli().program(), "podman");
74//! assert_eq!(deployment_v1::deployment(rendering).schema_version(), 1);
75//! # Ok::<(), Box<dyn std::error::Error>>(())
76//! ```
77
78#![forbid(unsafe_code)]
79
80/// Versioned, serialization-only deployment artifacts.
81pub mod artifact;
82pub mod connection;
83pub mod coverage;
84pub mod deployment;
85pub mod diagnostic;
86pub mod discovery;
87pub mod evidence;
88pub mod inventory;
89pub mod networking;
90pub mod observation;
91pub mod probe;
92#[cfg(unix)]
93pub mod read_only_unix_transport;
94pub mod render;
95pub mod runtime;
96pub mod settings;
97pub mod snapshot;
98pub mod transport;
99pub mod version;
100
101pub use connection::{
102    ConnectionKind, ConnectionSpec, MutualTlsPolicy, OpaqueReference, SshConnection, TcpMutualTlsConnection,
103    UnixConnection,
104};
105pub use coverage::{
106    NativeFieldCoverageClassification, NativeFieldCoverageEntry, NativeFieldCoveragePlane,
107    native_field_coverage_catalogue,
108};
109pub use deployment::{
110    ContainerIntent, DeploymentConnectionReference, DeploymentIntent, DeploymentOperation, DeploymentOperationId,
111    DeploymentPlan, DeploymentResource, DeploymentResourceId, ExternalPrecondition, ImageIntent, ImagePullPolicy,
112    ImageSource, ImageSourceClassification, NetworkIntent, PlanningFinding, PlanningOutcome, PodIntent, SecretIntent,
113    SemanticOperationAction, SensitiveInputReference, StartupDependency, VolumeIntent, plan_deployment,
114};
115pub use diagnostic::{Diagnostic, DiagnosticCode, PodmanLensResult};
116pub use discovery::{
117    DependencyEvidence, DiscoveryExplanation, DiscoveryExplanationKind, DiscoveryFinding, DiscoveryRequest,
118    DiscoveryRootOrigin, GroupingEdge, GroupingEvidence, LabelSelector, ResourceDependency, ResourceGraph,
119    ResourceGroup, ResourceSelector, ResourceSelectorMatch, discover,
120};
121pub use evidence::{CapabilityCatalogueEntry, EvidenceReference, capability_catalogue};
122pub use inventory::{
123    AcquisitionOptions, EnvironmentValuePolicy, InventoryFinding, InventorySection, InventorySectionAvailability,
124    JsonValueKind, MAX_INVENTORY_JSON_BYTES, MAX_UNKNOWN_FIELDS_PER_INVENTORY, MAX_UNKNOWN_FIELDS_PER_RECORD,
125    ResourceEvidence, ResourceIdentity, ResourceInventory, ResourceKind, SensitiveEnvironmentValue, acquire_inventory,
126};
127pub use networking::{
128    DnsConfiguration, HostAlias, NetworkAttachment, NetworkCidr, NetworkRoute, NetworkSubnet, PortMapping,
129    PortProtocol, RouteType, StaticMacAddress,
130};
131pub use observation::{
132    AuthoredImageSpellingHint, AuthoredMountRelabelHint, ConfiguredContainerCommand, ConfiguredContainerEntrypoint,
133    ConfiguredContainerHostname, ConfiguredContainerUser, ConfiguredContainerWorkdir, ContainerCreationEvidence,
134    ContainerMountKind, ContainerMountObservation, ContainerMountSelinuxRelabel, ContainerMountSource,
135    ContainerObservation, ContainerSecretGrantObservation, ContainerSecretReference, ImageObservation, Labels,
136    NativeCapability, NativeHealthCheckObservation, NativeHealthCommand, NativeHealthFailureAction,
137    NativeIpcNamespaceMode, NativeLogDriver, NativeLoggingObservation, NativeNamespaceMode, NativeNamespaceObservation,
138    NativeNetworkCidr, NativeNetworkLeaseRange, NativeNetworkRouteObservation, NativeNetworkRouteType,
139    NativeNetworkSubnetObservation, NativeNetworkingObservation, NativeOpaqueNetworkOptions,
140    NativeOpaqueSecurityOptions, NativePortBindingObservation, NativePortProtocol, NativeResourceControlObservation,
141    NativeResourceReference, NativeRestartPolicyName, NativeRestartPolicyObservation, NativeSecretDriverObservation,
142    NativeSecretDriverOptions, NativeSecurityObservation, NativeStartupHealthCheckObservation, NativeTimestamp,
143    NativeUlimitObservation, NetworkObservation, NetworkOptionKeys, ObservationField, ObservationHeader,
144    ObservationOrigin, ObservedValue, PodObservation, ProtectedEnvironment, ProtectedEnvironmentEntry,
145    ProtectedEnvironmentValue, ProtectedHealthCommand, ResourceDetails, ResourceObservation, ResourceObservationState,
146    SecretObservation, UnixId as ObservedUnixId, UnmodelledCompleteness, UnmodelledField, UnmodelledFieldId,
147    VolumeObservation, VolumeOwnerIdWireValue,
148};
149pub use probe::{MAX_PROBE_JSON_BYTES, ServiceObservation, probe_libpod_service};
150#[cfg(unix)]
151pub use read_only_unix_transport::{MIN_HTTP1_HEADER_BYTES, ReadOnlyUnixTransport, ReadOnlyUnixTransportTimeouts};
152pub use render::{
153    CliInvocation, DeploymentRendering, LibpodInvocation, RenderStatus, RenderedHttpBody, RenderedHttpMethod,
154    RenderedOperation, RenderingFinding, RenderingOutcome, render_deployment,
155};
156pub use runtime::{
157    ConfiguredHealthCheck, ContainerNamespaceSettings, ContainerResourceControls, ContainerRuntimeSettings,
158    HealthCheck, HealthCommand, HealthDuration, HealthInterval, HealthOnFailure, HealthRetries, HealthStartPeriod,
159    HealthTimeout, IpcNamespaceMode, LinuxCapability, LogDriver, LogSize, LoggingSettings, NamespaceMode,
160    PublicHealthArgumentArray, PublicHealthCommand, Rlimit, RlimitKind, RlimitValue, SecuritySettings,
161    SensitiveInlineHealthArgumentArray, SensitiveInlineHealthCommand, StartupHealthCheck, StartupHealthRetries,
162    StartupHealthSuccesses,
163};
164pub use settings::{
165    AbsoluteContainerPath, ArgumentArray, BindMount, ContainerHostname, ContainerSettings, ContainerUser,
166    ContainerWorkdir, DeploymentEnvironmentValue, EnvironmentAssignment, EnvironmentName, Label, LabelKey, MountAccess,
167    MountIntent, NamedVolumeCopyMode, NamedVolumeMount, PublicEnvironmentValue, PublicLabelValue, RestartPolicy,
168    SecretGrant, SecretMode, SensitiveInlineEnvironmentValue, TmpfsMount, UnixId, VolumeSubpath,
169};
170pub use transport::{
171    LibpodHeader, LibpodHeaders, LibpodMethod, LibpodPath, LibpodRequest, LibpodResponse, LibpodTransport,
172    LibpodTransportFuture, MAX_PATH_AND_QUERY_BYTES, TransportError, TransportLimits,
173};
174pub use version::{
175    CgroupCapabilityEvidence, CgroupController, CgroupVersion, ObservedApiVersion, ObservedPodmanVersion,
176    SupportedPodmanRange, TargetExecutionContext, TargetProfile,
177};
podman_lens/lib.rs

podman_lens/
lib.rs
