# HG changeset patch
# User Paul Fisher <paul@pfish.zone>
# Date 1751817566 14400
# Node ID 56b559b7ecea2cc83a846cf392cc1b6754187846
# Parent  ebb71a412b5864e822f60dc8826e5b59dad299cb
Big rename: separate concepts of Transaction from Handle.

- An application that uses PAM creates a Transaction.
- The Transaction has a Handle.

Currently, a module still get something called a "handle",
but that's probably going to change soon.

diff -r ebb71a412b58 -r 56b559b7ecea src/handle.rs
--- a/src/handle.rs	Sat Jul 05 22:12:46 2025 -0400
+++ b/src/handle.rs	Sun Jul 06 11:59:26 2025 -0400
@@ -59,7 +59,7 @@
 /// This base trait includes features of a PAM handle that are available
 /// to both applications and modules.
 ///
-/// You probably want [`LibPamHandle`](crate::libpam::OwnedLibPamHandle).
+/// You probably want [`LibPamTransaction`](crate::libpam::LibPamTransaction).
 /// This trait is intended to allow creating mock PAM handle types
 /// to test PAM modules and applications.
 pub trait PamShared {
@@ -268,7 +268,7 @@
 ///
 /// Like [`PamShared`], this is intended to allow creating mock implementations
 /// of PAM for testing PAM applications.
-pub trait PamHandleApplication: PamShared {
+pub trait Transaction: PamShared {
     /// Starts the authentication process for the user.
     ///
     /// The application calls this to find out who the user is, and verify that
diff -r ebb71a412b58 -r 56b559b7ecea src/lib.rs
--- a/src/lib.rs	Sat Jul 05 22:12:46 2025 -0400
+++ b/src/lib.rs	Sun Jul 06 11:59:26 2025 -0400
@@ -40,12 +40,12 @@
 
 #[cfg(feature = "link")]
 #[doc(inline)]
-pub use crate::libpam::{OwnedLibPamHandle, RawPamHandle};
+pub use crate::libpam::{LibPamHandle, LibPamTransaction};
 #[doc(inline)]
 pub use crate::{
     constants::{ErrorCode, Flags, Result},
     conv::{BinaryData, Conversation, ConversationAdapter},
     environ::{EnvironMap, EnvironMapMut},
-    handle::{PamHandleApplication, PamHandleModule, PamShared},
+    handle::{PamHandleModule, PamShared, Transaction},
     module::PamModule,
 };
diff -r ebb71a412b58 -r 56b559b7ecea src/libpam/environ.rs
--- a/src/libpam/environ.rs	Sat Jul 05 22:12:46 2025 -0400
+++ b/src/libpam/environ.rs	Sun Jul 06 11:59:26 2025 -0400
@@ -1,13 +1,13 @@
 use crate::environ::{EnvironMap, EnvironMapMut};
 use crate::libpam::memory::{CHeapBox, CHeapString};
-use crate::libpam::{memory, RawPamHandle};
+use crate::libpam::{memory, LibPamHandle};
 use std::ffi::{c_char, CStr, CString, OsStr, OsString};
 use std::marker::PhantomData;
 use std::os::unix::ffi::{OsStrExt, OsStringExt};
 use std::ptr;
 use std::ptr::NonNull;
 
-impl RawPamHandle {
+impl LibPamHandle {
     fn environ_get(&self, key: &OsStr) -> Option<OsString> {
         let key = CString::new(key.as_bytes()).ok()?;
         // SAFETY: We are a valid handle and are calling with a good key.
@@ -55,22 +55,22 @@
 
 /// A view to the environment stored in a PAM handle.
 pub struct LibPamEnviron<'a> {
-    source: &'a RawPamHandle,
+    source: &'a LibPamHandle,
 }
 
 /// A mutable view to the environment stored in a PAM handle.
 pub struct LibPamEnvironMut<'a> {
-    source: &'a mut RawPamHandle,
+    source: &'a mut LibPamHandle,
 }
 
 impl<'a> LibPamEnviron<'a> {
-    pub fn new(source: &'a RawPamHandle) -> Self {
+    pub fn new(source: &'a LibPamHandle) -> Self {
         Self { source }
     }
 }
 
 impl<'a> LibPamEnvironMut<'a> {
-    pub fn new(source: &'a mut RawPamHandle) -> Self {
+    pub fn new(source: &'a mut LibPamHandle) -> Self {
         Self { source }
     }
 }
@@ -113,7 +113,7 @@
     start: NonNull<Option<EnvVar>>,
     /// The environment variable we're about to iterate into.
     current: NonNull<Option<EnvVar>>,
-    _owner: PhantomData<&'a RawPamHandle>,
+    _owner: PhantomData<&'a LibPamHandle>,
 }
 
 impl EnvList<'_> {
diff -r ebb71a412b58 -r 56b559b7ecea src/libpam/handle.rs
--- a/src/libpam/handle.rs	Sat Jul 05 22:12:46 2025 -0400
+++ b/src/libpam/handle.rs	Sun Jul 06 11:59:26 2025 -0400
@@ -7,8 +7,7 @@
 use crate::libpam::memory;
 use crate::logging::{Level, Location};
 use crate::{
-    guide, linklist, stdlinks, Conversation, EnvironMap, Flags, PamHandleApplication,
-    PamHandleModule,
+    guide, linklist, stdlinks, Conversation, EnvironMap, Flags, PamHandleModule, Transaction,
 };
 use libpam_sys_helpers::constants;
 use num_enum::{IntoPrimitive, TryFromPrimitive};
@@ -20,9 +19,9 @@
 use std::ptr::NonNull;
 
 /// An owned PAM handle.
-pub struct OwnedLibPamHandle<C: Conversation> {
+pub struct LibPamTransaction<C: Conversation> {
     /// The handle itself.
-    handle: ManuallyDrop<RawPamHandle>,
+    handle: ManuallyDrop<LibPamHandle>,
     /// The last return value from the handle.
     last_return: Cell<Result<()>>,
     /// If set, the Conversation that this PAM handle owns.
@@ -36,12 +35,12 @@
 }
 
 #[derive(Debug, PartialEq)]
-pub struct HandleBuilder {
+pub struct TransactionBuilder {
     service_name: OsString,
     username: Option<OsString>,
 }
 
-impl HandleBuilder {
+impl TransactionBuilder {
     /// Updates the service name.
     pub fn service_name(mut self, service_name: OsString) -> Self {
         self.service_name = service_name;
@@ -55,12 +54,12 @@
         self
     }
     /// Builds a PAM handle and starts the transaction.
-    pub fn build(self, conv: impl Conversation) -> Result<OwnedLibPamHandle<impl Conversation>> {
-        OwnedLibPamHandle::start(self.service_name, self.username, conv)
+    pub fn build(self, conv: impl Conversation) -> Result<LibPamTransaction<impl Conversation>> {
+        LibPamTransaction::start(self.service_name, self.username, conv)
     }
 }
 
-impl<C: Conversation> OwnedLibPamHandle<C> {
+impl<C: Conversation> LibPamTransaction<C> {
     /// Creates a builder to start a PAM transaction for the given service.
     ///
     /// The service name is what controls the steps and checks PAM goes through
@@ -72,8 +71,8 @@
     ///
     #[doc = stdlinks!(3 pam_start)]
     #[doc = guide!(adg: "adg-interface-by-app-expected.html#adg-pam_start")]
-    pub fn build_with_service(service_name: OsString) -> HandleBuilder {
-        HandleBuilder {
+    pub fn build_with_service(service_name: OsString) -> TransactionBuilder {
+        TransactionBuilder {
             service_name,
             username: None,
         }
@@ -101,7 +100,7 @@
         ErrorCode::result_from(result)?;
         let handle = NonNull::new(handle).ok_or(ErrorCode::BufferError)?;
         Ok(Self {
-            handle: ManuallyDrop::new(RawPamHandle(handle)),
+            handle: ManuallyDrop::new(LibPamHandle(handle)),
             last_return: Cell::new(Ok(())),
             conversation: conv,
         })
@@ -128,7 +127,7 @@
     };
 }
 
-impl PamHandleApplication for RawPamHandle {
+impl Transaction for LibPamHandle {
     wrap!(fn authenticate { pam_authenticate });
     wrap!(fn account_management { pam_acct_mgmt });
     wrap!(fn change_authtok { pam_chauthtok });
@@ -144,7 +143,7 @@
 //       pam_getenv - shared
 //       pam_getenvlist - shared
 
-impl<C: Conversation> Drop for OwnedLibPamHandle<C> {
+impl<C: Conversation> Drop for LibPamTransaction<C> {
     /// Closes the PAM session on an owned PAM handle.
     ///
     /// This internally calls `pam_end` with the appropriate error code.
@@ -205,7 +204,7 @@
     result.as_ref().map(drop).map_err(|&e| e)
 }
 
-impl<C: Conversation> PamShared for OwnedLibPamHandle<C> {
+impl<C: Conversation> PamShared for LibPamTransaction<C> {
     delegate!(fn log(&self, level: Level, location: Location<'_>, entry: &str) -> ());
     delegate!(fn environ(&self) -> impl EnvironMap);
     delegate!(fn environ_mut(&mut self) -> impl EnvironMapMut);
@@ -237,14 +236,15 @@
 /// An owned variation of a basic PAM handle.
 ///
 /// This is the most basic version of a wrapped PAM handle. It's mostly used
-/// as the inside of the [`OwnedLibPamHandle`], but can also be used to "adopt"
+/// as the inside of the [`LibPamTransaction`], but can also be used to "adopt"
 /// a PAM handle created by another library.
 ///
 /// If [`Self::end`] is not called, this will always call `pam_end` reporting
 /// successful completion.
-pub struct RawPamHandle(NonNull<libpam_sys::pam_handle>);
+#[repr(transparent)]
+pub struct LibPamHandle(NonNull<libpam_sys::pam_handle>);
 
-impl RawPamHandle {
+impl LibPamHandle {
     /// Takes ownership of the pointer to the given PAM handle.
     ///
     /// **Do not use this just to get a reference to a PAM handle.**
@@ -317,13 +317,13 @@
     }
 }
 
-impl Drop for RawPamHandle {
+impl Drop for LibPamHandle {
     fn drop(&mut self) {
         unsafe { libpam_sys::pam_end(self.0.as_mut(), 0) };
     }
 }
 
-impl PamShared for RawPamHandle {
+impl PamShared for LibPamHandle {
     #[cfg(any())]
     fn log(&self, level: Level, loc: Location<'_>, entry: &str) {
         let entry = match CString::new(entry).or_else(|_| CString::new(dbg!(entry))) {
@@ -393,7 +393,7 @@
     cstr_item!(set = set_old_authtok_item, item = ItemType::OldAuthTok);
 }
 
-impl Conversation for RawPamHandle {
+impl Conversation for LibPamHandle {
     fn communicate(&self, messages: &[Exchange]) {
         match self.conversation_item() {
             Ok(conv) => conv.communicate(messages),
@@ -406,7 +406,7 @@
     }
 }
 
-impl PamHandleModule for RawPamHandle {
+impl PamHandleModule for LibPamHandle {
     fn authtok(&mut self, prompt: Option<&OsStr>) -> Result<OsString> {
         self.get_authtok(prompt, ItemType::AuthTok)
     }
@@ -430,7 +430,7 @@
 }
 
 // Implementations of internal functions.
-impl RawPamHandle {
+impl LibPamHandle {
     #[cfg(any(pam_impl = "LinuxPam", pam_impl = "OpenPam"))]
     fn get_authtok(&mut self, prompt: Option<&OsStr>, item_type: ItemType) -> Result<OsString> {
         let prompt = memory::option_cstr_os(prompt);
diff -r ebb71a412b58 -r 56b559b7ecea src/libpam/mod.rs
--- a/src/libpam/mod.rs	Sat Jul 05 22:12:46 2025 -0400
+++ b/src/libpam/mod.rs	Sun Jul 06 11:59:26 2025 -0400
@@ -15,4 +15,4 @@
 mod question;
 
 #[doc(inline)]
-pub use handle::{OwnedLibPamHandle, RawPamHandle};
+pub use handle::{LibPamHandle, LibPamTransaction};
diff -r ebb71a412b58 -r 56b559b7ecea src/libpam/module.rs
--- a/src/libpam/module.rs	Sat Jul 05 22:12:46 2025 -0400
+++ b/src/libpam/module.rs	Sun Jul 06 11:59:26 2025 -0400
@@ -11,7 +11,7 @@
 ///
 /// ```no_run
 /// use nonstick::{
-///     pam_hooks, ConversationAdapter, Flags, OwnedLibPamHandle, PamHandleModule, PamModule,
+///     pam_hooks, ConversationAdapter, Flags, LibPamTransaction, PamHandleModule, PamModule,
 ///     Result as PamResult,
 /// };
 /// use std::ffi::CStr;
@@ -42,7 +42,7 @@
     ($ident:ident) => {
         mod _pam_hooks_scope {
             use std::ffi::{c_char, c_int, c_void, CStr};
-            use $crate::{ErrorCode, Flags, PamModule, RawPamHandle};
+            use $crate::{ErrorCode, Flags, LibPamHandle, PamModule};
 
             #[no_mangle]
             extern "C" fn pam_sm_acct_mgmt(
@@ -51,7 +51,7 @@
                 argc: c_int,
                 argv: *const *const c_char,
             ) -> c_int {
-                if let Some(handle) = unsafe { pamh.cast::<RawPamHandle>().as_mut() } {
+                if let Some(handle) = unsafe { pamh.cast::<LibPamHandle>().as_mut() } {
                     let args = extract_argv(argc, argv);
                     ErrorCode::result_to_c(super::$ident::account_management(handle, args, flags))
                 } else {
@@ -66,7 +66,7 @@
                 argc: c_int,
                 argv: *const *const c_char,
             ) -> c_int {
-                if let Some(handle) = unsafe { pamh.cast::<RawPamHandle>().as_mut() } {
+                if let Some(handle) = unsafe { pamh.cast::<LibPamHandle>().as_mut() } {
                     let args = extract_argv(argc, argv);
                     ErrorCode::result_to_c(super::$ident::authenticate(handle, args, flags))
                 } else {
@@ -81,7 +81,7 @@
                 argc: c_int,
                 argv: *const *const c_char,
             ) -> c_int {
-                if let Some(handle) = unsafe { pamh.cast::<RawPamHandle>().as_mut() } {
+                if let Some(handle) = unsafe { pamh.cast::<LibPamHandle>().as_mut() } {
                     let args = extract_argv(argc, argv);
                     ErrorCode::result_to_c(super::$ident::change_authtok(handle, args, flags))
                 } else {
@@ -96,7 +96,7 @@
                 argc: c_int,
                 argv: *const *const c_char,
             ) -> c_int {
-                if let Some(handle) = unsafe { pamh.cast::<RawPamHandle>().as_mut() } {
+                if let Some(handle) = unsafe { pamh.cast::<LibPamHandle>().as_mut() } {
                     let args = extract_argv(argc, argv);
                     ErrorCode::result_to_c(super::$ident::close_session(handle, args, flags))
                 } else {
@@ -112,7 +112,7 @@
                 argv: *const *const c_char,
             ) -> c_int {
                 let args = extract_argv(argc, argv);
-                if let Some(handle) = unsafe { pamh.cast::<RawPamHandle>().as_mut() } {
+                if let Some(handle) = unsafe { pamh.cast::<LibPamHandle>().as_mut() } {
                     ErrorCode::result_to_c(super::$ident::open_session(handle, args, flags))
                 } else {
                     ErrorCode::Ignore as c_int
@@ -127,7 +127,7 @@
                 argv: *const *const c_char,
             ) -> c_int {
                 let args = extract_argv(argc, argv);
-                if let Some(handle) = unsafe { pamh.cast::<RawPamHandle>().as_mut() } {
+                if let Some(handle) = unsafe { pamh.cast::<LibPamHandle>().as_mut() } {
                     ErrorCode::result_to_c(super::$ident::set_credentials(handle, args, flags))
                 } else {
                     ErrorCode::Ignore as c_int