docs

mirrord/layer/src/exec_hooks/hooks.rs

@@ -17,6 +17,8 @@ use crate::{
     SOCKETS,
 };
 
+/// Converts the [`SOCKETS`] map into a vector of pairs `(Fd, UserSocket)`, so we can rebuild
+/// it as a map.
 #[tracing::instrument(level = Level::TRACE, ret)]
 fn shared_sockets() -> Vec<(i32, UserSocket)> {
     SOCKETS
@@ -25,6 +27,11 @@ fn shared_sockets() -> Vec<(i32, UserSocket)> {
         .collect::<Vec<_>>()
 }
 
+/// Takes an [`Argv`] with the enviroment variables from an `exec` call, extending it with
+/// an encoded version of our [`SOCKETS`].
+///
+/// The check for [`libc::FD_CLOEXEC`] is performed during the [`SOCKETS`] initialization
+/// by the child process.
 #[mirrord_layer_macro::instrument(
     level = Level::DEBUG,
     ret,
@@ -43,13 +50,18 @@ pub(crate) fn execve(env_vars: Detour<Argv>) -> Detour<*const *const c_char> {
     Detour::Success(env_vars.leak())
 }
 
+/// Hook for `libc::execv` for linux only.
+///
+/// On macos this just calls `execve(path, argv, _environ)`, so we'll be handling it in our
+/// [`execve_detour`].
 #[cfg(not(target_os = "macos"))]
 #[hook_guard_fn]
 unsafe extern "C" fn execv_detour(path: *const c_char, argv: *const *const c_char) -> c_int {
     let encoded = bincode::encode_to_vec(shared_sockets(), bincode::config::standard())
         .map(|bytes| BASE64_URL_SAFE.encode(bytes))
         .unwrap_or_default();
 
+    // `encoded` is emtpy if the encoding failed, so we don't set the env var.
     if !encoded.is_empty() {
         std::env::set_var("MIRRORD_SHARED_SOCKETS", encoded);
     }
@@ -59,6 +71,8 @@ unsafe extern "C" fn execv_detour(path: *const c_char, argv: *const *const c_cha
 
 /// Hook for `libc::execve`.
 ///
+/// We can't change the pointers, to get around that we create our own and **leak** them.
+///
 /// - #[cfg(target_os = "macos")]
 ///
 /// We change 3 arguments and then call the original functions:
@@ -102,6 +116,7 @@ pub(crate) unsafe extern "C" fn execve_detour(
     }
 }
 
+/// Enables `exec` hooks.
 pub(crate) unsafe fn enable_exec_hooks(hook_manager: &mut HookManager) {
     #[cfg(not(target_os = "macos"))]
     replace!(hook_manager, "execv", execv_detour, FnExecv, FN_EXECV);

mirrord/layer/src/socket.rs

@@ -37,7 +37,22 @@ pub(crate) mod ops;
 
 pub(crate) const SHARED_SOCKETS_ENV_VAR: &str = "MIRRORD_SHARED_SOCKETS";
 
-/// TODO(alex) [mid]: Document this and say don't log stuff in here, maybe doc stack size issue?
+/// Stores the [`UserSocket`]s created by the user.
+///
+/// **Warning**: Do not put logs in here! If you try logging stuff inside this initialization
+/// you're gonna have a bad time. The process hanging is the min you should expect, if you
+/// choose to ignore this warning.
+///
+/// - [`SHARED_SOCKETS_ENV_VAR`]: Some sockets may have been initialized by a parent process
+/// through [`libc::execve`] (or any `exec*`), and the spawned children may want to use those
+/// sockets. As memory is not shared via `exec*` calls (unlike `fork`), we need a way to pass
+/// parent sockets to child processes. The way we achieve this is by setting the
+/// [`SHARED_SOCKETS_ENV_VAR`] with an [`BASE64_URL_SAFE`] encoded version of our [`SOCKETS`].
+/// The env var is set as `MIRRORD_SHARED_SOCKETS=({fd}, {UserSocket}),*`.
+///
+/// - [`libc::FD_CLOEXEC`] behaviour: While rebuilding sockets from the env var, we also
+/// check if they're set with the cloexec flag, so that children processes don't end up using
+/// sockets that are exclusive for their parents.
 pub(crate) static SOCKETS: LazyLock<DashMap<RawFd, Arc<UserSocket>>> = LazyLock::new(|| {
     std::env::var(SHARED_SOCKETS_ENV_VAR)
         .ok()