strand_cam/

strand-cam.rs

// Copyright (C) The Strand-Braid Authors
// SPDX-License-Identifier: MIT OR Apache-2.0

// TODO: if camera not available, launch alternate UI indicating such and
// waiting for it to become available?

// TODO: add quit app button to UI.

// TODO: UI automatically reconnect to app after app restart.

use async_change_tracker::ChangeTracker;
use event_stream_types::{
    AcceptsEventStream, ConnectionEvent, ConnectionEventType, ConnectionSessionKey,
    EventBroadcaster, TolerantJson,
};
use futures::stream::StreamExt;
use http::StatusCode;
use strand_http_video_streaming as video_streaming;

use machine_vision_formats as formats;
use preferences_serde1::{AppInfo, Preferences};
use serde::{Deserialize, Serialize};
use tokio::sync::mpsc::error::SendError;
use tracing::{debug, error, info, trace, warn};

use ci2::{Camera, CameraInfo, CameraModule, DynamicFrameWithInfo};
use ci2_async::AsyncCamera;
use fmf::FMFWriter;
use formats::PixFmt;
use strand_bui_backend_session_types::{BuiServerAddrInfo, ConnectionKey};
use strand_dynamic_frame::DynamicFrame;

use video_streaming::AnnotatedFrame;

use std::{path::PathBuf, pin::Pin, result::Result as StdResult};

/// Map [`ci2::Error::FeatureNotPresent`] to a fallback value, propagating any
/// other error. Backends such as the webcam backend report controls they
/// cannot provide this way; using a fallback lets the startup path degrade
/// gracefully instead of aborting when a control is unavailable.
fn feature_or<T>(result: ci2::Result<T>, fallback: T) -> ci2::Result<T> {
    match result {
        Err(ci2::Error::FeatureNotPresent()) => Ok(fallback),
        other => other,
    }
}

#[cfg(feature = "flydra_feat_detect")]
use strand_cam_remote_control::CsvSaveConfig;
use strand_cam_remote_control::{
    CamArg, CodecSelection, FfmpegCodecArgs, FfmpegRecordingConfig, Mp4Codec, Mp4RecordingConfig,
    NvidiaH264Options, RecordingFrameRate,
};

use braid_types::{BuiServerInfo, RawCamName, StartSoftwareFrameRateLimit, TriggerType};

use flydra_feature_detector_types::ImPtDetectCfg;

#[cfg(feature = "flydra_feat_detect")]
use strand_cam_csv_config_types::CameraCfgFview2_0_26;

#[cfg(feature = "fiducial")]
use strand_cam_storetype::ApriltagState;
use strand_cam_storetype::{
    CallbackType, ImOpsState, RangedValue, STRAND_CAM_EVENT_NAME, StoreType, ToLedBoxDevice,
};

use strand_cam_storetype::{KalmanTrackingConfig, LedProgramConfig};

use std::{
    io::Write,
    net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr, UdpSocket},
    sync::{Arc, RwLock},
};

pub const APP_INFO: AppInfo = AppInfo {
    name: "strand-cam",
    author: "AndrewStraw",
};

pub use flydra_pt_detect_cfg::default_absdiff as default_im_pt_detect;

#[cfg(feature = "bundle_files")]
static ASSETS_DIR: include_dir::Dir<'static> =
    include_dir::include_dir!("$CARGO_MANIFEST_DIR/yew_frontend/dist");

#[cfg(feature = "flydratrax")]
const KALMAN_TRACKING_PREFS_KEY: &str = "kalman-tracking";

#[cfg(feature = "flydratrax")]
const LED_PROGRAM_PREFS_KEY: &str = "led-config";

const COOKIE_SECRET_KEY: &str = "cookie-secret-base64";
const BRAID_COOKIE_KEY: &str = "braid-cookie";

#[cfg(feature = "flydratrax")]
mod flydratrax_handle_msg;

mod clock_model;
mod datagram_socket;
mod post_trigger_buffer;

#[cfg(feature = "eframe-gui")]
mod gui_app;

mod frame_process_task;

mod cam_arg_task;
mod cam_stream_task;
mod http_router;
mod led_box_task;
use frame_process_task::frame_process_task;

#[cfg(feature = "eframe-gui")]
#[derive(Default)]
struct GuiShared {
    ctx: Option<eframe::egui::Context>,
    url: Option<String>,
}

#[cfg(feature = "eframe-gui")]
type ArcMutGuiSingleton = Arc<std::sync::Mutex<GuiShared>>;

#[cfg(not(feature = "eframe-gui"))]
type ArcMutGuiSingleton = ();

pub mod cli_app;

const LED_BOX_HEARTBEAT_INTERVAL_MSEC: u64 = 5000;

use eyre::{Result, WrapErr, eyre};

pub(crate) enum Msg {
    StartMp4,
    StopMp4,
    StartFMF((String, RecordingFrameRate)),
    StopFMF,
    #[cfg(feature = "flydra_feat_detect")]
    StartUFMF(String),
    #[cfg(feature = "flydra_feat_detect")]
    StopUFMF,
    #[cfg(feature = "flydra_feat_detect")]
    SetTracking(bool),
    PostTriggerStartMp4,
    SetPostTriggerBufferSize(usize),
    Mframe(DynamicFrameWithInfo),
    #[cfg(feature = "flydra_feat_detect")]
    SetIsSavingObjDetectionCsv(CsvSaveConfig),
    #[cfg(feature = "flydra_feat_detect")]
    SetExpConfig(ImPtDetectCfg),
    Store(Arc<RwLock<ChangeTracker<StoreType>>>),
    #[cfg(feature = "flydra_feat_detect")]
    TakeCurrentImageAsBackground,
    #[cfg(feature = "flydra_feat_detect")]
    ClearBackground(f32),
    SetFrameOffset(u64),
    SetTriggerboxClockModel(Option<strand_cam_bui_types::ClockModel>),
    StartAprilTagRec(String),
    StopAprilTagRec,
}

impl std::fmt::Debug for Msg {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> StdResult<(), std::fmt::Error> {
        write!(f, "strand_cam::Msg{{..}}")
    }
}

#[derive(Debug, PartialEq, Clone, Serialize, Deserialize, Default)]
pub enum FrameProcessingErrorState {
    #[default]
    NotifyAll,
    IgnoreUntil(chrono::DateTime<chrono::Utc>),
    IgnoreAll,
}

#[cfg(feature = "flydra_feat_detect")]
#[derive(Debug, PartialEq, Clone, Serialize, Deserialize)]
pub enum Tracker {
    NoTracker,
    BackgroundSubtraction(ImPtDetectCfg),
}

/// Which timestamp source is used to estimate the frame rate.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum FpsTimestampSource {
    /// A trigger-derived timestamp (external trigger box, PTP sync, or the
    /// device clock mapped through a clock model). Most preferred: it reflects
    /// the true acquisition time and is available whenever a trigger is
    /// configured — including for cameras that expose no usable raw hardware
    /// timestamp — so it is usable in more cases than the device timestamp.
    Trigger,
    /// The camera's hardware/device timestamp. Used when no trigger is in use.
    /// It reflects the true acquisition time and is immune to host-side
    /// buffering, so the estimate is correct even when frames are delivered to
    /// the host in bursts.
    Hardware,
    /// The host clock sampled when the frame was grabbed. Last-resort fallback
    /// used when neither a trigger timestamp nor a camera hardware timestamp is
    /// available. Under load the driver buffers frames and the host grabs them
    /// in bursts, so this can read several times too high.
    HostClock,
}

pub struct FpsCalc {
    /// (frame number, timestamp in nanoseconds) of the last sample.
    prev: Option<(usize, i128)>,
    frames_to_average: usize,
    /// The source of the current running sample. Only differences within a
    /// single source are meaningful (epochs differ between sources), so the
    /// estimate is reset whenever the source changes.
    source: Option<FpsTimestampSource>,
}

impl FpsCalc {
    /// create a new FpsCalc instance
    pub fn new(frames_to_average: usize) -> Self {
        Self {
            prev: None,
            frames_to_average,
            source: None,
        }
    }
    /// Update with a frame number and a timestamp (nanoseconds) from `source`,
    /// returning a newly computed fps whenever available.
    ///
    /// The timestamp epoch is irrelevant (only differences are used), but it
    /// must be consistent within a source, so the running estimate restarts
    /// whenever `source` changes.
    pub fn update(
        &mut self,
        fno: usize,
        stamp_nanos: i128,
        source: FpsTimestampSource,
    ) -> Option<f64> {
        if self.source != Some(source) {
            // Source changed (or first sample): restart the estimate.
            self.source = Some(source);
            self.prev = Some((fno, stamp_nanos));
            return None;
        }
        let mut reset_previous = true;
        let mut result = None;
        if let Some((prev_frame, prev_stamp)) = self.prev {
            let n_frames = fno - prev_frame;
            if n_frames < self.frames_to_average {
                reset_previous = false;
            } else {
                let dur_nsec = stamp_nanos - prev_stamp;
                if dur_nsec > 0 {
                    result = Some(n_frames as f64 / dur_nsec as f64 * 1.0e9);
                }
            }
        }
        if reset_previous {
            self.prev = Some((fno, stamp_nanos));
        }
        result
    }
}

#[cfg(test)]
mod fps_calc_tests {
    use super::{FpsCalc, FpsTimestampSource};

    const NS_PER_S: i128 = 1_000_000_000;

    /// With the camera hardware timestamp (true cadence), the estimated rate is
    /// correct even when frames are delivered to the host in bursts. This is the
    /// fix for the live-vs-retrack fragmentation bug.
    #[test]
    fn hardware_timestamp_is_robust_to_bursty_delivery() {
        let mut fc = FpsCalc::new(100);
        let true_fps = 30.0;
        let dt_ns = (NS_PER_S as f64 / true_fps) as i128; // true inter-frame, ns
        let mut measured = None;
        for fno in 0..=100usize {
            // Hardware timestamp advances at the true cadence regardless of when
            // the host actually grabbed the frame.
            let stamp = fno as i128 * dt_ns;
            if let Some(fps) = fc.update(fno, stamp, FpsTimestampSource::Hardware) {
                measured = Some(fps);
            }
        }
        let fps = measured.expect("should produce an estimate after 100 frames");
        assert!(
            (fps - true_fps).abs() < 0.1,
            "hardware fps {fps} != {true_fps}"
        );
    }

    /// The trigger timestamp (the preferred source) is likewise robust to
    /// bursty host-side delivery, since it reflects the true acquisition cadence
    /// rather than when the host grabbed each frame.
    #[test]
    fn trigger_timestamp_is_robust_to_bursty_delivery() {
        let mut fc = FpsCalc::new(100);
        let true_fps = 30.0;
        let dt_ns = (NS_PER_S as f64 / true_fps) as i128; // true inter-frame, ns
        let mut measured = None;
        for fno in 0..=100usize {
            let stamp = fno as i128 * dt_ns;
            if let Some(fps) = fc.update(fno, stamp, FpsTimestampSource::Trigger) {
                measured = Some(fps);
            }
        }
        let fps = measured.expect("should produce an estimate after 100 frames");
        assert!(
            (fps - true_fps).abs() < 0.1,
            "trigger fps {fps} != {true_fps}"
        );
    }

    /// Demonstrates the bug being fixed: with the host clock, a burst (e.g. the
    /// driver delivering 100 buffered frames in ~1/3 of the true span) makes the
    /// estimate read far too high.
    #[test]
    fn host_clock_overreads_under_bursty_delivery() {
        let mut fc = FpsCalc::new(100);
        let true_fps = 30.0;
        // 100 frames truly span 100/30 s, but the host grabbed them bunched into
        // 1/3 of that wall-clock time.
        let bunched_span_ns = (100.0 / true_fps / 3.0 * NS_PER_S as f64) as i128;
        let mut measured = None;
        for fno in 0..=100usize {
            let stamp = (fno as i128 * bunched_span_ns) / 100;
            if let Some(fps) = fc.update(fno, stamp, FpsTimestampSource::HostClock) {
                measured = Some(fps);
            }
        }
        let fps = measured.unwrap();
        assert!(fps > 80.0, "expected an inflated host-clock fps, got {fps}");
    }

    /// Changing the timestamp source restarts the estimate (epochs differ
    /// between sources, so a cross-source delta would be meaningless).
    #[test]
    fn changing_source_resets_estimate() {
        let mut fc = FpsCalc::new(2);
        assert_eq!(fc.update(0, 0, FpsTimestampSource::Hardware), None);
        // Switch source at frame 2: must not compute across the boundary.
        assert_eq!(fc.update(2, 999_999, FpsTimestampSource::HostClock), None);
        // Now consistent host-clock samples produce an estimate.
        let dt = NS_PER_S / 30;
        assert_eq!(fc.update(2, 0, FpsTimestampSource::HostClock), None);
        let fps = fc.update(4, 2 * dt, FpsTimestampSource::HostClock).unwrap();
        assert!((fps - 30.0).abs() < 0.5, "fps {fps}");
    }
}

struct FmfWriteInfo<T>
where
    T: std::io::Write + std::io::Seek,
{
    writer: FMFWriter<T>,
    recording_framerate: RecordingFrameRate,
    last_saved_stamp: Option<chrono::DateTime<chrono::Utc>>,
}

impl<T> FmfWriteInfo<T>
where
    T: std::io::Write + std::io::Seek,
{
    fn new(writer: FMFWriter<T>, recording_framerate: RecordingFrameRate) -> Self {
        Self {
            writer,
            recording_framerate,
            last_saved_stamp: None,
        }
    }
}

#[cfg(feature = "checkercal")]
type CollectedCornersArc = Arc<RwLock<Vec<Vec<(f32, f32)>>>>;

async fn convert_stream(
    raw_cam_name: RawCamName,
    mut transmit_feature_detect_settings_rx: tokio::sync::mpsc::Receiver<
        flydra_feature_detector_types::ImPtDetectCfg,
    >,
    transmit_msg_tx: tokio::sync::mpsc::Sender<braid_types::BraidHttpApiCallback>,
) -> Result<()> {
    while let Some(val) = transmit_feature_detect_settings_rx.recv().await {
        let msg =
            braid_types::BraidHttpApiCallback::UpdateFeatureDetectSettings(braid_types::PerCam {
                raw_cam_name: raw_cam_name.clone(),
                inner: braid_types::UpdateFeatureDetectSettings {
                    current_feature_detect_settings: val,
                },
            });
        transmit_msg_tx.send(msg).await?;
    }
    Ok(())
}

/// Find the local source IP address the OS would use to reach `remote_ip`.
///
/// Uses a UDP socket `connect()` (which performs endpoint association and
/// routing/source-address selection without sending application payload) to ask
/// the OS which local IP it would use for traffic to `remote_ip`.
///
/// Note: this is a local routing decision only. It does not guarantee that a
/// remote peer can connect back (for example due to NAT or firewall rules).
fn find_local_ip_for_remote(remote_ip: IpAddr) -> std::io::Result<IpAddr> {
    let bind_addr: SocketAddr = match remote_ip {
        IpAddr::V4(_) => SocketAddr::new(IpAddr::V4(Ipv4Addr::UNSPECIFIED), 0),
        IpAddr::V6(_) => SocketAddr::new(IpAddr::V6(Ipv6Addr::UNSPECIFIED), 0),
    };
    let socket = UdpSocket::bind(bind_addr)?;
    // Port 1 is arbitrary; UDP connect() only records the routing decision.
    socket.connect(SocketAddr::new(remote_ip, 1))?;
    Ok(socket.local_addr()?.ip())
}

/// Decide the HTTP server listen address that strand-cam should bind to and
/// advertise to Braid when running in the Braid context.
///
/// Braid must be able to connect back to this strand-cam's HTTP server (see
/// `docs/.../braid_remote_cameras.md`). The address is chosen as follows:
///
/// - If Braid's per-camera config provides an explicit `http_server_addr`
///   override, always use it verbatim.
/// - Otherwise, if Braid is on loopback, bind loopback (`127.0.0.1:0`).
/// - Otherwise (Braid is remote), use `resolver` to find the local source IP
///   the OS would use to reach Braid, so Braid can connect back to it. If that
///   fails, warn and fall back to loopback (which will likely fail for a remote
///   Braid, but is the safest local default).
///
/// `resolver` is injected (rather than calling [`find_local_ip_for_remote`]
/// directly) so the decision logic can be unit-tested without real sockets.
fn braid_strand_cam_http_address(
    mainbrain_ip: IpAddr,
    http_server_addr_override: Option<String>,
    resolver: impl FnOnce(IpAddr) -> std::io::Result<IpAddr>,
) -> String {
    if mainbrain_ip.is_loopback() {
        http_server_addr_override.unwrap_or_else(|| "127.0.0.1:0".to_string())
    } else {
        http_server_addr_override.unwrap_or_else(|| {
            // When braid is on a different machine it must connect back to this
            // strand-cam's HTTP server. Find the outgoing interface IP that
            // braid can reach.
            match resolver(mainbrain_ip) {
                Ok(local_ip) => format!("{local_ip}:0"),
                Err(e) => {
                    tracing::warn!(
                        "Could not determine local IP for braid at {mainbrain_ip}: {e}. \
                        Falling back to 127.0.0.1, which may fail for remote connections."
                    );
                    "127.0.0.1:0".to_string()
                }
            }
        })
    }
}

fn open_braid_destination_addr(camdata_udp_addr: &SocketAddr) -> Result<UdpSocket> {
    info!(
        "Sending detected coordinates via UDP to: {}",
        camdata_udp_addr
    );

    let timeout = std::time::Duration::new(0, 1);

    let src_ip = if !camdata_udp_addr.ip().is_loopback() {
        // Let OS choose what IP to use, but preserve V4 or V6.
        match camdata_udp_addr {
            SocketAddr::V4(_) => IpAddr::V4(Ipv4Addr::new(0, 0, 0, 0)),
            SocketAddr::V6(_) => IpAddr::V6(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 0)),
        }
    } else {
        match camdata_udp_addr {
            SocketAddr::V4(_) => IpAddr::V4(Ipv4Addr::LOCALHOST),
            SocketAddr::V6(_) => IpAddr::V6(Ipv6Addr::LOCALHOST),
        }
    };
    // Let OS choose what port to use.
    let src_addr = SocketAddr::new(src_ip, 0);

    let sock = UdpSocket::bind(src_addr)?;
    sock.set_write_timeout(Some(timeout))?;
    sock.connect(camdata_udp_addr)?;
    Ok(sock)
}

#[cfg(feature = "flydra_feat_detect")]
fn get_intensity(device_state: &strand_led_box_comms::DeviceState, chan_num: u8) -> u16 {
    let ch: &strand_led_box_comms::ChannelState = match chan_num {
        1 => &device_state.ch1,
        2 => &device_state.ch2,
        3 => &device_state.ch3,
        c => panic!("unknown channel {c}"),
    };
    match ch.on_state {
        strand_led_box_comms::OnState::Off => 0,
        strand_led_box_comms::OnState::ConstantOn => ch.intensity,
    }
}

/// Ignore a send error.
///
/// During shutdown, the receiver can disappear before the sender is closed.
/// According to the docs of the `send` method of [tokio::sync::mpsc::Sender],
/// this is the only way we can get a [tokio::sync::mpsc::error::SendError].
/// Therefore, we ignore the error.
trait IgnoreSendError {
    fn ignore_send_error(self);
}

impl<T: std::fmt::Debug> IgnoreSendError for StdResult<(), tokio::sync::mpsc::error::SendError<T>> {
    fn ignore_send_error(self) {
        match self {
            Ok(()) => {}
            Err(e) => {
                debug!("Ignoring send error ({}:{}): {:?}", file!(), line!(), e)
            }
        }
    }
}

#[derive(Clone)]
struct StrandCamCallbackSenders {
    firehose_callback_tx: tokio::sync::mpsc::Sender<ConnectionKey>,
    cam_args_tx: tokio::sync::mpsc::Sender<CamArg>,
    led_box_tx_std: tokio::sync::mpsc::Sender<ToLedBoxDevice>,
    #[cfg_attr(not(feature = "flydra_feat_detect"), expect(unused))]
    tx_frame: tokio::sync::mpsc::Sender<Msg>,
}

#[derive(Clone)]
struct StrandCamAppState {
    cam_name: String,
    event_broadcaster: EventBroadcaster<ConnectionSessionKey>,
    callback_senders: StrandCamCallbackSenders,
    tx_new_connection: tokio::sync::mpsc::Sender<event_stream_types::ConnectionEvent>,
    shared_store_arc: Arc<RwLock<ChangeTracker<StoreType>>>,
    /// The address the HTTP server is bound to (possibly unspecified, e.g.
    /// `0.0.0.0`), used to enumerate device-connection URLs on demand.
    bui_server_info: strand_bui_backend_session_types::BuiServerAddrInfo,
    /// The cookie/token secret, used to mint a fresh short-lived access token
    /// when a device-connection QR code is requested.
    persistent_secret: cookie::Key,
}

fn display_qr_url(url: &str) -> Result<()> {
    use qrcode::QrCode;
    use qrcode::render::unicode;
    use std::io::stdout;

    let qr = QrCode::new(url)?;

    let image = qr.render::<unicode::Dense1x2>().build();

    let stdout = stdout();
    let mut stdout_handle = stdout.lock();
    writeln!(stdout_handle)?;
    stdout_handle.write_all(image.as_bytes())?;
    writeln!(stdout_handle)?;
    Ok(())
}

#[derive(Debug, Clone)]
/// Defines whether runtime changes from the user are persisted to disk.
///
/// If they are persisted to disk, upon program re-start, the disk
/// is checked and preferences are loaded from there. If they cannot
/// be loaded, the defaults are used.
pub enum ImPtDetectCfgSource {
    ChangesNotSavedToDisk(ImPtDetectCfg),
    ChangedSavedToDisk((&'static AppInfo, String)),
}

#[cfg(feature = "flydra_feat_detect")]
impl Default for ImPtDetectCfgSource {
    fn default() -> Self {
        ImPtDetectCfgSource::ChangesNotSavedToDisk(default_im_pt_detect())
    }
}

#[derive(Debug, PartialEq, Eq, Serialize, Deserialize, Clone)]
pub enum TimestampSource {
    BraidTrigger, // TODO: rename to CleverComputation or similar
    HostAcquiredTimestamp,
}

const MOMENT_CENTROID_SCHEMA_VERSION: u8 = 2;

#[derive(Debug, PartialEq, Serialize, Deserialize, Clone)]
pub struct MomentCentroid {
    pub schema_version: u8,
    pub framenumber: u64,
    pub timestamp_source: TimestampSource,
    pub timestamp: chrono::DateTime<chrono::Utc>,
    pub mu00: f32,
    pub mu01: f32,
    pub mu10: f32,
    pub center_x: u32,
    pub center_y: u32,
    #[serde(default)]
    pub cam_name: String,
}

#[derive(Debug, Serialize, Deserialize)]
enum CentroidToDevice {
    Centroid(MomentCentroid),
}

/// CLI args for the case when we will connect to Braid.
///
/// Prior to the connection, we don't know much about what our configuration
/// should be. This is very limited because most configuration should be done in
/// the Braid configuration .toml file.
#[derive(Debug, Default, Clone)]
pub struct BraidArgs {
    pub braid_url: String,
    pub camera_name: String,
}

/// CLI args for the case when we run standalone.
#[derive(Debug, Clone, Default)]
pub struct StandaloneArgs {
    pub camera_name: Option<String>,
    /// The HTTP socket address for the Strand Cam BUI.
    pub http_server_addr: Option<String>,
    pub pixel_format: Option<String>,
    /// If set, camera acquisition will external trigger.
    pub force_camera_sync_mode: bool,
    /// If enabled, limit framerate (FPS) at startup.
    ///
    /// Despite the name ("software"), this actually sets the hardware
    /// acquisition rate via the `AcquisitionFrameRate` camera parameter.
    pub software_limit_framerate: StartSoftwareFrameRateLimit,
    /// Threshold duration before logging error (msec).
    ///
    /// If the image acquisition timestamp precedes the computed trigger
    /// timestamp, clearly an error has happened. This error must lie in the
    /// computation of the trigger timestamp. This specifies the threshold error
    /// at which an error is logged. (The underlying source of such errors
    /// remains unknown.)
    pub acquisition_duration_allowed_imprecision_msec: Option<f64>,
    /// Filename of vendor-specific camera settings file.
    pub camera_settings_filename: Option<std::path::PathBuf>,
    #[cfg(feature = "flydra_feat_detect")]
    pub tracker_cfg_src: ImPtDetectCfgSource,
}

#[derive(Debug)]
pub enum StandaloneOrBraid {
    Standalone(StandaloneArgs),
    Braid(BraidArgs),
}

impl Default for StandaloneOrBraid {
    fn default() -> Self {
        Self::Standalone(Default::default())
    }
}

/// Default filename template for saved `.mp4` recordings.
pub(crate) const MP4_FILENAME_TEMPLATE_DEFAULT: &str = "movie%Y%m%d_%H%M%S.%f_{CAMNAME}.mp4";
/// Default filename template for saved `.fmf` recordings.
pub(crate) const FMF_FILENAME_TEMPLATE_DEFAULT: &str = "movie%Y%m%d_%H%M%S.%f_{CAMNAME}.fmf";
/// Default filename template for saved `.ufmf` recordings.
pub(crate) const UFMF_FILENAME_TEMPLATE_DEFAULT: &str = "movie%Y%m%d_%H%M%S.%f_{CAMNAME}.ufmf";

#[derive(Debug)]
pub struct StrandCamArgs {
    /// Is Strand Cam running inside Braid context?
    pub standalone_or_braid: StandaloneOrBraid,
    /// base64 encoded secret. minimum 256 bits.
    pub secret: Option<String>,
    /// Client networks (CIDR, e.g. `100.64.0.0/10`) trusted to have already
    /// authenticated the peer (e.g. Tailscale/WireGuard). Requests from these
    /// networks are accepted without an access token.
    pub trusted_networks: Vec<String>,
    pub no_browser: bool,
    pub mp4_filename_template: String,
    pub fmf_filename_template: String,
    pub ufmf_filename_template: String,
    pub disable_console: bool,
    pub csv_save_dir: String,
    pub led_box_device_path: Option<String>,
    #[cfg(feature = "flydratrax")]
    pub save_empty_data2d: SaveEmptyData2dType,
    #[cfg(feature = "flydratrax")]
    pub model_server_addr: std::net::SocketAddr,
    #[cfg(feature = "flydratrax")]
    pub flydratrax_calibration_source: CalSource,
    #[cfg(feature = "fiducial")]
    pub apriltag_csv_filename_template: String,
    #[cfg(feature = "flydratrax")]
    pub write_buffer_size_num_messages: usize,
    #[cfg(target_os = "linux")]
    v4l2loopback: Option<PathBuf>,
    data_dir: Option<PathBuf>,
}

pub type SaveEmptyData2dType = bool;

#[derive(Debug)]
pub enum CalSource {
    /// Use circular tracking region to create calibration
    PseudoCal,
    /// Use flydra .xml file with single camera for calibration
    XmlFile(std::path::PathBuf),
    /// Use pymvg .json file with single camera for calibration
    PymvgJsonFile(std::path::PathBuf),
}

impl Default for StrandCamArgs {
    fn default() -> Self {
        Self {
            standalone_or_braid: Default::default(),
            secret: None,
            trusted_networks: Vec::new(),
            no_browser: true,
            mp4_filename_template: MP4_FILENAME_TEMPLATE_DEFAULT.to_string(),
            fmf_filename_template: FMF_FILENAME_TEMPLATE_DEFAULT.to_string(),
            ufmf_filename_template: UFMF_FILENAME_TEMPLATE_DEFAULT.to_string(),
            disable_console: false,
            #[cfg(feature = "fiducial")]
            apriltag_csv_filename_template: strand_cam_storetype::APRILTAG_CSV_TEMPLATE_DEFAULT
                .to_string(),
            csv_save_dir: "/dev/null".to_string(),
            led_box_device_path: None,
            #[cfg(feature = "flydratrax")]
            flydratrax_calibration_source: CalSource::PseudoCal,
            #[cfg(feature = "flydratrax")]
            save_empty_data2d: true,
            #[cfg(feature = "flydratrax")]
            model_server_addr: braid_types::DEFAULT_MODEL_SERVER_ADDR.parse().unwrap(),
            #[cfg(feature = "flydratrax")]
            write_buffer_size_num_messages:
                braid_config_data::default_write_buffer_size_num_messages(),
            #[cfg(target_os = "linux")]
            v4l2loopback: None,
            data_dir: Default::default(),
        }
    }
}

fn test_nvenc_save(frame: DynamicFrame) -> Result<bool> {
    let cfg = Mp4RecordingConfig {
        codec: Mp4Codec::H264NvEnc(NvidiaH264Options {
            bitrate: None,
            cuda_device: 0,
        }),
        h264_metadata: None,
        max_framerate: RecordingFrameRate::Fps30,
    };
    let mut nv_cfg_test = cfg.clone();

    let libs = match nvenc::Dynlibs::new() {
        Ok(libs) => libs,
        Err(e) => {
            debug!("nvidia NvEnc library could not be loaded: {:?}", e);
            return Ok(false);
        }
    };

    let opts = NvidiaH264Options {
        bitrate: None,
        ..Default::default()
    };

    nv_cfg_test.codec = strand_cam_remote_control::Mp4Codec::H264NvEnc(opts);

    // Temporary variable to hold file data. This will be dropped
    // at end of scope.
    let mut buf = std::io::Cursor::new(Vec::new());

    let nv_enc = match nvenc::NvEnc::new(&libs) {
        Ok(nv_enc) => nv_enc,
        Err(e) => {
            debug!("nvidia NvEnc could not be initialized: {:?}", e);
            return Ok(false);
        }
    };

    let mut mp4_writer = mp4_writer::Mp4Writer::new(&mut buf, nv_cfg_test, Some(nv_enc))?;
    match mp4_writer.write_dynamic(&frame, chrono::Local::now()) {
        Ok(()) => {}
        Err(e) => {
            debug!("nvidia NvEnc could not be initialized: {:?}", e);
            return Ok(false);
        }
    }
    mp4_writer.finish()?;

    debug!("MP4 video with nvenc h264 encoding succeeded.");

    // When `buf` goes out of scope, it will be dropped.
    Ok(true)
}

fn to_event_chunk(state: &StoreType) -> String {
    let buf = serde_json::to_string(&state).unwrap();
    format!("event: {STRAND_CAM_EVENT_NAME}\ndata: {buf}\n\n")
}

/// Handle a new connection to the event stream.
///
/// This creates a new channel which sends events to the new connection. The
/// receiver side is simply the http body passed to axum. The sender side is
/// initially started with a couple messages and then is ultimately sent to a
/// "global event sender" which will send ongoing events to all connections.
async fn events_handler(
    axum::extract::State(app_state): axum::extract::State<StrandCamAppState>,
    session_key: axum_token_auth::SessionKey,
    axum::extract::ConnectInfo(addr): axum::extract::ConnectInfo<SocketAddr>,
    _: AcceptsEventStream,
) -> impl axum::response::IntoResponse {
    session_key.is_present();
    tracing::trace!("events");
    // Connection wants to subscribe to event stream.

    let key = ConnectionSessionKey::new(session_key.0, addr);

    // Create a new channel in which the receiver is used to send responses to
    // the new connection. The sender is sent to the app where it is stored in a
    // per-connection map. Changes for this connection will then be sent to the
    // stored sender.
    let (conn_tx, body) = app_state.event_broadcaster.new_connection(key);

    // Send the first message, the connection key.
    {
        let chunk = format!(
            "event: {}\ndata: {}\n\n",
            strand_cam_storetype::CONN_KEY_EVENT_NAME,
            addr
        );
        match conn_tx.send(http_body::Frame::data(chunk.into())).await {
            Ok(()) => {}
            Err(tokio::sync::mpsc::error::SendError(_)) => {
                // The receiver was dropped because the connection closed. Should probably do more here.
                tracing::debug!("initial send error");
            }
        }
    }

    // Send the second message, a copy of our state.
    {
        let shared_store = app_state.shared_store_arc.read().unwrap().as_ref().clone();
        let chunk = to_event_chunk(&shared_store);
        match conn_tx.send(http_body::Frame::data(chunk.into())).await {
            Ok(()) => {}
            Err(tokio::sync::mpsc::error::SendError(_)) => {
                // The receiver was dropped because the connection closed. Should probably do more here.
                tracing::debug!("initial send error");
            }
        }
    }

    // Finally, send `tx`, the sender of the newly created channel, to the
    // "global event sender" which will send further events to the connection.
    {
        let typ = ConnectionEventType::Connect(conn_tx);
        let connection_key = ConnectionKey { addr };

        match app_state
            .tx_new_connection
            .send(ConnectionEvent {
                typ,
                connection_key,
            })
            .await
        {
            Ok(()) => Ok(body),
            Err(_) => Err((
                StatusCode::INTERNAL_SERVER_ERROR,
                "sending new connection failed",
            )),
        }
    }
}

async fn cam_name_handler(
    axum::extract::State(app_state): axum::extract::State<StrandCamAppState>,
    session_key: axum_token_auth::SessionKey,
) -> impl axum::response::IntoResponse {
    session_key.is_present();
    app_state.cam_name.clone()
}

/// Returns the URLs (one per reachable network interface) at which this web UI
/// can be reached, each carrying a freshly minted short-lived access token. The
/// frontend turns these into QR codes for connecting another device.
async fn device_connect_urls_handler(
    axum::extract::State(app_state): axum::extract::State<StrandCamAppState>,
    session_key: axum_token_auth::SessionKey,
) -> impl axum::response::IntoResponse {
    session_key.is_present();
    build_device_connect_urls(&app_state.bui_server_info, &app_state.persistent_secret)
}

/// Build the [`DeviceConnectUrls`] response: enumerate the interfaces the server
/// is reachable on and mint a fresh access token (unless bound to loopback).
///
/// [`DeviceConnectUrls`]: strand_bui_backend_session_types::DeviceConnectUrls
fn build_device_connect_urls(
    bui_server_info: &strand_bui_backend_session_types::BuiServerAddrInfo,
    persistent_secret: &cookie::Key,
) -> axum::response::Response {
    use axum::response::IntoResponse;
    use strand_bui_backend_session_types::{AccessToken, BuiServerAddrInfo, DeviceConnectUrls};

    let bound = *bui_server_info.addr();
    // Match the token policy of `braid_types::start_listener`: a token is only
    // required (and only useful) when the server is not bound to loopback.
    let token = if bound.ip().is_loopback() {
        AccessToken::NoToken
    } else {
        AccessToken::PreSharedToken(axum_token_auth::generate_token(
            persistent_secret,
            braid_types::ACCESS_TOKEN_TTL,
        ))
    };
    let info = BuiServerAddrInfo::new(bound, token);
    let uris = match strand_bui_backend_session::build_urls(&info) {
        Ok(uris) => uris,
        Err(e) => {
            return (
                axum::http::StatusCode::INTERNAL_SERVER_ERROR,
                format!("failed to enumerate network interfaces: {e}"),
            )
                .into_response();
        }
    };
    let loopback_only = uris.iter().all(braid_types::is_loopback);
    let urls = uris.into_iter().map(|u| u.to_string()).collect();
    axum::Json(DeviceConnectUrls {
        urls,
        loopback_only,
    })
    .into_response()
}

async fn callback_handler(
    axum::extract::State(app_state): axum::extract::State<StrandCamAppState>,
    session_key: axum_token_auth::SessionKey,
    TolerantJson(payload): TolerantJson<CallbackType>,
) -> axum::response::Response {
    use axum::response::IntoResponse;
    session_key.is_present();
    tracing::trace!("callback");
    match payload {
        CallbackType::ToCamera(cam_arg) => {
            // Validate YAML strings before enqueuing so callers get a proper
            // error response instead of a silent HTTP 200 with config discarded.
            let yaml_err: Option<String> = match &cam_arg {
                #[cfg(feature = "flydra_feat_detect")]
                CamArg::SetObjDetectionConfig(y) => serde_yaml::from_str::<ImPtDetectCfg>(y)
                    .err()
                    .map(|e| e.to_string()),
                #[cfg(feature = "flydratrax")]
                CamArg::CamArgSetKalmanTrackingConfig(y) => {
                    serde_yaml::from_str::<KalmanTrackingConfig>(y)
                        .err()
                        .map(|e| e.to_string())
                }
                #[cfg(feature = "flydratrax")]
                CamArg::CamArgSetLedProgramConfig(y) => serde_yaml::from_str::<LedProgramConfig>(y)
                    .err()
                    .map(|e| e.to_string()),
                _ => None,
            };
            if let Some(e) = yaml_err {
                return (
                    StatusCode::UNPROCESSABLE_ENTITY,
                    format!("YAML parse error: {e}"),
                )
                    .into_response();
            }
            debug!("in cb: {:?}", cam_arg);
            app_state
                .callback_senders
                .cam_args_tx
                .send(cam_arg)
                .await
                .ignore_send_error();
        }
        CallbackType::FirehoseNotify(ck) => {
            app_state
                .callback_senders
                .firehose_callback_tx
                .send(ck)
                .await
                .ignore_send_error();
        }
        CallbackType::TakeCurrentImageAsBackground => {
            #[cfg(feature = "flydra_feat_detect")]
            app_state
                .callback_senders
                .tx_frame
                .send(Msg::TakeCurrentImageAsBackground)
                .await
                .ignore_send_error();
        }
        CallbackType::ClearBackground(value) => {
            #[cfg(feature = "flydra_feat_detect")]
            app_state
                .callback_senders
                .tx_frame
                .send(Msg::ClearBackground(value))
                .await
                .ignore_send_error();
            #[cfg(not(feature = "flydra_feat_detect"))]
            let _ = value;
        }
        CallbackType::ToLedBox(led_box_arg) => futures::executor::block_on(async {
            info!("in led_box callback: {:?}", led_box_arg);
            app_state
                .callback_senders
                .led_box_tx_std
                .send(led_box_arg)
                .await
                .ignore_send_error();
        }),
    }
    ().into_response()
}

async fn handle_auth_error(err: tower::BoxError) -> (StatusCode, &'static str) {
    match err.downcast::<axum_token_auth::ValidationErrors>() {
        Ok(err) => {
            tracing::error!(
                "Validation error(s): {:?}",
                err.errors().collect::<Vec<_>>()
            );
            (StatusCode::UNAUTHORIZED, "Request is not authorized")
        }
        Err(orig_err) => {
            tracing::error!("Unhandled internal error: {orig_err}");
            (StatusCode::INTERNAL_SERVER_ERROR, "internal server error")
        }
    }
}

/// Information acquired from Braid when the HTTP session is established.
#[derive(Debug)]
struct BraidInfo {
    mainbrain_bui_loc: BuiServerAddrInfo,

    mainbrain_session: braid_http_session::MainbrainSession,
    /// The address to which low-latency tracking data should be sent.
    ///
    /// Neither the IP nor the port are unspecified.
    camdata_udp_addr: SocketAddr,
    #[cfg_attr(not(feature = "flydra_feat_detect"), expect(dead_code))]
    tracker_cfg_src: ImPtDetectCfgSource,
    config_from_braid: braid_types::RemoteCameraInfoResponse,
}

/// Wrapper to enforce that first message is fixed to be
/// [braid_types::RegisterNewCamera].
struct FirstMsgForced {
    tx: tokio::sync::mpsc::Sender<braid_types::BraidHttpApiCallback>,
}

impl FirstMsgForced {
    fn channel(
        sz: usize,
    ) -> (
        Self,
        tokio::sync::mpsc::Receiver<braid_types::BraidHttpApiCallback>,
    ) {
        let (tx, rx) = tokio::sync::mpsc::channel(sz);
        (Self { tx }, rx)
    }

    /// Send the first message and return the Sender.
    async fn send_first_msg(
        self,
        new_cam_data: braid_types::RegisterNewCamera,
    ) -> std::result::Result<
        tokio::sync::mpsc::Sender<braid_types::BraidHttpApiCallback>,
        tokio::sync::mpsc::error::SendError<braid_types::BraidHttpApiCallback>,
    > {
        self.tx
            .send(braid_types::BraidHttpApiCallback::NewCamera(new_cam_data))
            .await?;
        Ok(self.tx)
    }
}

// -----------

/// top-level function once args are parsed from CLI.
pub fn run_strand_cam_app<M, C, G>(
    mymod: ci2_async::ThreadedAsyncCameraModule<M, C, G>,
    args: StrandCamArgs,
    app_name: &'static str,
) -> Result<ci2_async::ThreadedAsyncCameraModule<M, C, G>>
where
    M: ci2::CameraModule<CameraType = C, Guard = G> + 'static,
    C: 'static + ci2::Camera + Send,
    G: Send + 'static,
{
    let (log_dir, data_dir) = if let Some(data_dir) = &args.data_dir {
        (data_dir.clone(), data_dir.clone())
    } else {
        (
            // default log_dir is home.
            home::home_dir().ok_or_else(|| {
                eyre::eyre!("Could not determine home directory and data directory not set.")
            })?,
            // default data_dir is pwd.
            PathBuf::from("."),
        )
    };

    // Initial log file name has process ID in case multiple cameras are
    // launched simultaneously. The (still open) log file gets renamed later to
    // include the camera name. We need to start logging as soon as possible
    // (before we necessarily know the camera name) because we may need to debug
    // connectivity problems to Braid or problems starting the camera.
    let log_file_time = chrono::Local::now();
    let initial_log_file_name = log_file_time
        .format(".strand-cam-%Y%m%d_%H%M%S.%f")
        .to_string()
        + &format!("-{}.log", std::process::id());
    let initial_log_file_name = log_dir.join(&initial_log_file_name);
    // TODO: delete log files older than, e.g. one week.

    #[cfg(feature = "eframe-gui")]
    let disable_console = true;

    #[cfg(not(feature = "eframe-gui"))]
    let disable_console = args.disable_console;

    let initial_log_file_name2 = initial_log_file_name.clone();

    let _guard =
        env_tracing_logger::initiate_logging(Some(&initial_log_file_name2), disable_console)
            .map_err(|e| eyre!("error initiating logging: {e}"))?;

    // create tokio runtime
    let runtime = tokio::runtime::Builder::new_multi_thread()
        .enable_all()
        .worker_threads(4)
        .thread_name("strand-cam-runtime")
        .thread_stack_size(3 * 1024 * 1024)
        .build()?;

    let log_file_info = LogFileInfo {
        initial_log_file_name,
        log_dir,
        data_dir,
        log_file_time,
    };

    #[cfg(feature = "eframe-gui")]
    {
        let (quit_tx, quit_rx) = tokio::sync::mpsc::channel(1);

        let gui_singleton = Arc::new(std::sync::Mutex::new(GuiShared::default()));
        let gui_singleton2 = gui_singleton.clone();

        let (frame_tx, frame_rx) = tokio::sync::watch::channel(Arc::new(
            strand_dynamic_frame::DynamicFrameOwned::from_static(
                formats::owned::OImage::<formats::pixel_format::Mono8>::zeros(0, 0, 0).unwrap(),
            ),
        ));
        let (egui_ctx_tx, egui_ctx_rx) = std::sync::mpsc::channel();

        let gui_app_stuff = Some(GuiAppStuff {
            quit_rx,
            frame_tx,
            egui_ctx_rx,
        });

        // Move tokio runtime to new thread to keep GUI event loop on initial thread.
        let tokio_thread_jh = std::thread::Builder::new()
            .name("tokio-thread".to_string())
            .spawn(move || {
                let mymod = runtime.block_on(run_after_maybe_connecting_to_braid(
                    mymod,
                    args,
                    app_name,
                    log_file_info,
                    gui_app_stuff,
                    gui_singleton2,
                ))?;

                info!("done");
                Ok(mymod)
            })
            .map_err(|e| eyre::anyhow!("runtime failed with error {e}"))?;

        let native_options = Default::default();

        eframe::run_native(
            "Strand Camera",
            native_options,
            Box::new(move |cc| {
                Ok(Box::new(gui_app::StrandCamEguiApp::new(
                    quit_tx,
                    cc,
                    gui_singleton,
                    frame_rx,
                    egui_ctx_tx,
                )))
            }),
        )
        .map_err(|e| eyre::anyhow!("running failed with error {e}"))?;

        // Block until tokio done.
        tokio_thread_jh.join().unwrap()
    }

    #[cfg(not(feature = "eframe-gui"))]
    {
        let gui_singleton = ();

        let mymod = runtime.block_on(run_after_maybe_connecting_to_braid(
            mymod,
            args,
            app_name,
            log_file_info,
            None,
            gui_singleton,
        ))?;

        info!("done");
        Ok(mymod)
    }
}

struct GuiAppStuff {
    quit_rx: tokio::sync::mpsc::Receiver<()>,
    #[cfg(feature = "eframe-gui")]
    frame_tx: tokio::sync::watch::Sender<gui_app::ImType>,
    #[cfg(feature = "eframe-gui")]
    egui_ctx_rx: std::sync::mpsc::Receiver<eframe::egui::Context>,
}

/// Connect to the braid server and return information.
///
/// Store cookie if set by braid so that next connection does not need token.
async fn connect_to_braid(braid_args: &BraidArgs) -> Result<BraidInfo> {
    info!("Will connect to braid at \"{}\"", braid_args.braid_url);
    let mainbrain_bui_loc = BuiServerAddrInfo::parse_url_with_token(&braid_args.braid_url)?;

    let jar: cookie_store::CookieStore = match Preferences::load(&APP_INFO, BRAID_COOKIE_KEY) {
        Ok(jar) => {
            tracing::debug!("loaded cookie store {BRAID_COOKIE_KEY}");
            jar
        }
        Err(e) => {
            tracing::debug!("cookie store {BRAID_COOKIE_KEY} not loaded: {e} {e:?}");
            cookie_store::CookieStore::new(None)
        }
    };
    let jar = Arc::new(RwLock::new(jar));
    let mut mainbrain_session =
        braid_http_session::create_mainbrain_session(mainbrain_bui_loc.clone(), jar.clone())
            .await
            .with_context(|| format!("While connecting to Braid at {}", braid_args.braid_url))?;
    tracing::debug!("Opened HTTP session with Braid.");
    {
        // We have the cookie from braid now, so store it to disk.
        let jar = jar.read().unwrap();
        Preferences::save(&*jar, &APP_INFO, BRAID_COOKIE_KEY)?;
        // The jar holds live session cookies; keep its file owner-only.
        braid_types::harden_prefs_file(&APP_INFO, BRAID_COOKIE_KEY);
        tracing::debug!("saved cookie store {BRAID_COOKIE_KEY}");
    }

    let camera_name = braid_types::RawCamName::new(braid_args.camera_name.clone());

    let config_from_braid: braid_types::RemoteCameraInfoResponse =
        mainbrain_session.get_remote_info(&camera_name).await?;

    let camdata_udp_ip = mainbrain_bui_loc.addr().ip();
    let camdata_udp_port = config_from_braid.camdata_udp_port;
    let camdata_udp_addr = SocketAddr::new(camdata_udp_ip, camdata_udp_port);

    let tracker_cfg_src = crate::ImPtDetectCfgSource::ChangesNotSavedToDisk(
        config_from_braid.config.point_detection_config.clone(),
    );

    Ok(BraidInfo {
        mainbrain_bui_loc,
        mainbrain_session,
        config_from_braid,
        camdata_udp_addr,
        tracker_cfg_src,
    })
}

struct LogFileInfo {
    initial_log_file_name: PathBuf,
    /// where log files are saved
    log_dir: PathBuf,
    /// where movies are saved
    data_dir: PathBuf,
    log_file_time: chrono::DateTime<chrono::Local>,
}

/// First, connect to Braid if requested, then run.
async fn run_after_maybe_connecting_to_braid<M, C, G>(
    mymod: ci2_async::ThreadedAsyncCameraModule<M, C, G>,
    args: StrandCamArgs,
    app_name: &'static str,
    log_file_info: LogFileInfo,
    gui_app_stuff: Option<GuiAppStuff>,
    gui_singleton: ArcMutGuiSingleton,
) -> Result<ci2_async::ThreadedAsyncCameraModule<M, C, G>>
where
    M: ci2::CameraModule<CameraType = C, Guard = G>,
    C: 'static + ci2::Camera + Send,
    G: Send,
{
    let cfg_from_braid;
    let strand_cam_bui_http_address_string = match &args.standalone_or_braid {
        StandaloneOrBraid::Braid(braid_args) => {
            // Connect to braid and get configuration if running in braid context.
            let from_mainbrain = connect_to_braid(braid_args).await?;

            // We have already connected to the Mainbrain BUI server and gotten
            // configuration information from it. Use that to set things up.
            let http_server_addr = from_mainbrain
                .config_from_braid
                .config
                .http_server_addr
                .clone();
            let mainbrain_bui_loc = &from_mainbrain.mainbrain_bui_loc;

            let strand_cam_bui_http_address_string = braid_strand_cam_http_address(
                mainbrain_bui_loc.addr().ip(),
                http_server_addr,
                find_local_ip_for_remote,
            );
            cfg_from_braid = Some(from_mainbrain);
            strand_cam_bui_http_address_string
        }
        StandaloneOrBraid::Standalone(standalone_args) => {
            cfg_from_braid = None;
            // The best way I've found to set the default value because we need
            // to keep `http_server_addr` None when calling from Braid. If we
            // change the default, we also need to change the docs and
            // docstrings.
            const BRAID_HTTP_ADDR: &str = "127.0.0.1:3440";
            standalone_args
                .http_server_addr
                .clone()
                .unwrap_or_else(|| BRAID_HTTP_ADDR.to_string())
        }
    };
    tracing::debug!("Strand Camera HTTP server: {strand_cam_bui_http_address_string}");

    let target_feature_string = target::features().join(", ");
    info!("Compiled with features: {}", target_feature_string);

    let requested_camera_name = match &args.standalone_or_braid {
        StandaloneOrBraid::Standalone(args) => args.camera_name.clone(),
        StandaloneOrBraid::Braid(args) => Some(args.camera_name.clone()),
    };

    debug!("Request for camera \"{requested_camera_name:?}\"");

    // -----------------------------------------------

    info!("camera module: {}", mymod.name());

    let cam_infos = mymod.camera_infos()?;
    if cam_infos.is_empty() {
        eyre::bail!("No cameras found.");
    }

    for cam_info in cam_infos.iter() {
        info!("  camera {:?} detected", cam_info.name());
    }

    let use_camera_name = match requested_camera_name {
        Some(ref name) => name,
        None => cam_infos[0].name(),
    };

    // Rename the log file (which is open and being written to) so that the name
    // includes the camera name.
    let new_log_file_name = log_file_info
        .log_file_time
        .format(".strand-cam-%Y%m%d_%H%M%S.%f")
        .to_string()
        + &format!("-{}.log", use_camera_name);
    let new_log_file_name = log_file_info.log_dir.join(&new_log_file_name);

    tracing::debug!(
        "Renaming log file \"{}\" -> \"{}\"",
        log_file_info.initial_log_file_name.display(),
        new_log_file_name.display()
    );
    std::fs::rename(&log_file_info.initial_log_file_name, &new_log_file_name).with_context(
        || {
            format!(
                "Renaming log file \"{}\" -> \"{}\"",
                log_file_info.initial_log_file_name.display(),
                new_log_file_name.display()
            )
        },
    )?;

    run(
        mymod,
        args,
        app_name,
        cfg_from_braid,
        strand_cam_bui_http_address_string,
        use_camera_name,
        gui_app_stuff,
        gui_singleton,
        log_file_info.data_dir,
    )
    .await
}

// -----------

/// Forward messages from elsewhere in Strand Cam to mainbrain.
///
/// The future runs until the trainsmit_msg_rx channel is closed otherwise ends
/// only on error.
async fn forward_to_mainbrain(
    mut transmit_msg_rx: tokio::sync::mpsc::Receiver<braid_types::BraidHttpApiCallback>,
    mut mainbrain_session: braid_http_session::MainbrainSession,
) -> Result<()> {
    while let Some(msg) = transmit_msg_rx.recv().await {
        // We have a message from elsewhere in Strand Cam to send to mainbrain.
        mainbrain_session
            .post_callback_message(msg)
            .await
            .context("failed sending message to mainbrain")?;
    }
    Ok(())
}

// -----------

/// This is the main function where we spend all time after parsing startup args
/// and, in case of connecting to braid, getting the inital connection
/// information.
///
/// This function is way too huge and should be refactored.
#[tracing::instrument(skip(
    mymod,
    args,
    app_name,
    braid_info,
    strand_cam_bui_http_address_string,
    gui_app_stuff,
    gui_singleton,
    data_dir
))]
#[expect(
    clippy::too_many_arguments,
    reason = "oh this is ugly. refactor at some point."
)]
async fn run<M, C, G>(
    mut mymod: ci2_async::ThreadedAsyncCameraModule<M, C, G>,
    args: StrandCamArgs,
    app_name: &'static str,
    braid_info: Option<BraidInfo>,
    strand_cam_bui_http_address_string: String,
    cam: &str,
    gui_app_stuff: Option<GuiAppStuff>,
    gui_singleton: ArcMutGuiSingleton,
    data_dir: PathBuf,
) -> Result<ci2_async::ThreadedAsyncCameraModule<M, C, G>>
where
    M: ci2::CameraModule<CameraType = C, Guard = G>,
    C: 'static + ci2::Camera + Send,
    G: Send,
{
    let use_camera_name = cam; // simple arg name important for tracing::instrument
    let settings_file_ext = mymod.settings_file_extension().to_string();

    let (quit_rx, gui_stuff2) = if let Some(gas) = gui_app_stuff {
        let quit_rx = gas.quit_rx;

        #[cfg(feature = "eframe-gui")]
        let gui_stuff2 = {
            let frame_tx = gas.frame_tx;
            let egui_ctx_rx = gas.egui_ctx_rx;

            // Wait for egui context.
            let egui_ctx: eframe::egui::Context = egui_ctx_rx.recv().unwrap();

            Some((frame_tx, egui_ctx))
        };

        #[cfg(not(feature = "eframe-gui"))]
        let gui_stuff2: Option<()> = None;

        (Some(quit_rx), gui_stuff2)
    } else {
        (None, None)
    };

    let mut cam = match mymod.threaded_async_camera(use_camera_name) {
        Ok(cam) => cam,
        Err(e) => {
            let msg = format!("{e}");
            error!("{}", msg);
            return Err(e.into());
        }
    };

    let raw_name = cam.name().to_string();
    info!("  got camera {}", raw_name);
    let raw_cam_name = RawCamName::new(raw_name);

    let camera_gamma = cam
        .feature_float("Gamma")
        .map_err(|e| warn!("Ignoring error getting gamma: {}", e))
        .ok()
        .map(|x: f64| x as f32);

    // Use `Result` as an enum with two options. It's not the case that one is a
    // non-error and the other an error condition. We just use `Result` rather
    // than defining our own enum type here.
    let res_braid = match (&braid_info, &args.standalone_or_braid) {
        (Some(bi), StandaloneOrBraid::Braid(_)) => Ok(bi),
        (None, StandaloneOrBraid::Standalone(a)) => Err(a),
        (Some(_), StandaloneOrBraid::Standalone(_)) | (None, StandaloneOrBraid::Braid(_)) => {
            unreachable!()
        }
    };

    let camera_settings_filename = match &res_braid {
        Ok(bi) => bi.config_from_braid.config.camera_settings_filename.clone(),
        Err(a) => a.camera_settings_filename.clone(),
    };

    let pixel_format = match &res_braid {
        Ok(bi) => bi.config_from_braid.config.pixel_format.clone(),
        Err(a) => a.pixel_format.clone(),
    };

    let send_image_to_braid_interval = res_braid.as_ref().ok().map(|bi| {
        std::time::Duration::from_millis(
            bi.config_from_braid.config.send_current_image_interval_msec,
        )
    });

    let acquisition_duration_allowed_imprecision_msec = match &res_braid {
        Ok(bi) => {
            bi.config_from_braid
                .config
                .acquisition_duration_allowed_imprecision_msec
        }
        Err(a) => a.acquisition_duration_allowed_imprecision_msec,
    };
    #[cfg(not(feature = "flydra_feat_detect"))]
    let _ = acquisition_duration_allowed_imprecision_msec;

    let (frame_rate_limit_supported, mut frame_rate_limit_enabled) = if let Some(fname) =
        &camera_settings_filename
    {
        let settings = std::fs::read_to_string(fname).with_context(|| {
            format!(
                "Failed to read camera settings from file \"{}\"",
                fname.display()
            )
        })?;

        cam.node_map_load(&settings)?;
        info!("loaded camera settings file \"{}\"", fname.display());
        (false, false)
    } else {
        for pixfmt in cam.possible_pixel_formats()?.iter() {
            debug!("  possible pixel format: {}", pixfmt);
        }

        if let Some(ref pixfmt_str) = pixel_format {
            use std::str::FromStr;
            let pixfmt = PixFmt::from_str(pixfmt_str).map_err(|e: &str| eyre!(e.to_string()))?;
            info!("  setting pixel format: {}", pixfmt);
            cam.set_pixel_format(pixfmt)?;
        }

        debug!("  current pixel format: {}", cam.pixel_format()?);

        let (frame_rate_limit_supported, frame_rate_limit_enabled) = {
            // This entire section should be removed and converted to a query
            // of the cameras capabilities.

            // Save the value of whether the frame rate limiter is enabled.
            let frame_rate_limit_enabled = feature_or(cam.acquisition_frame_rate_enable(), false)?;
            debug!("frame_rate_limit_enabled {}", frame_rate_limit_enabled);

            // Check if we can set the frame rate, first by setting a limit to be on.
            let frame_rate_limit_supported = match cam.set_acquisition_frame_rate_enable(true) {
                Ok(()) => {
                    debug!("set set_acquisition_frame_rate_enable true");
                    // Then by setting a limit to be off.
                    match cam.set_acquisition_frame_rate_enable(false) {
                        Ok(()) => {
                            debug!("{}:{}", file!(), line!());
                            true
                        }
                        Err(e) => {
                            debug!("err {} {}:{}", e, file!(), line!());
                            false
                        }
                    }
                }
                Err(e) => {
                    debug!("err {} {}:{}", e, file!(), line!());
                    false
                }
            };

            if frame_rate_limit_supported {
                // Restore the state of the frame rate limiter.
                cam.set_acquisition_frame_rate_enable(frame_rate_limit_enabled)?;
                debug!("set frame_rate_limit_enabled {}", frame_rate_limit_enabled);
            }

            (frame_rate_limit_supported, frame_rate_limit_enabled)
        };

        match cam.feature_enum_set("AcquisitionMode", "Continuous") {
            Ok(()) => {}
            Err(e) => {
                debug!("Ignoring error when setting AcquisitionMode: {}", e);
            }
        }
        (frame_rate_limit_supported, frame_rate_limit_enabled)
    };

    let settings_on_start = feature_or(cam.node_map_save(), String::new())?;

    let res_braid = match (&braid_info, &args.standalone_or_braid) {
        (Some(bi), StandaloneOrBraid::Braid(_)) => Ok(bi),
        (None, StandaloneOrBraid::Standalone(a)) => Err(a),
        (Some(_), StandaloneOrBraid::Standalone(_)) | (None, StandaloneOrBraid::Braid(_)) => {
            unreachable!()
        }
    };

    let force_camera_sync_mode = match &res_braid {
        Ok(bi) => bi.config_from_braid.force_camera_sync_mode,
        Err(a) => a.force_camera_sync_mode,
    };

    let camdata_udp_addr = match &res_braid {
        Ok(bi) => Some(bi.camdata_udp_addr),
        Err(_a) => None,
    };

    let software_limit_framerate = match &res_braid {
        Ok(bi) => bi.config_from_braid.software_limit_framerate.clone(),
        Err(a) => a.software_limit_framerate.clone(),
    };

    #[cfg(feature = "flydra_feat_detect")]
    let tracker_cfg_src = match &res_braid {
        Ok(bi) => bi.tracker_cfg_src.clone(),
        Err(a) => a.tracker_cfg_src.clone(),
    };

    // Here we just create some default, it does not matter what, because it
    // will not be used for anything.
    #[cfg(not(feature = "flydra_feat_detect"))]
    let im_pt_detect_cfg = flydra_pt_detect_cfg::default_absdiff();

    #[cfg(feature = "flydra_feat_detect")]
    let im_pt_detect_cfg = match &tracker_cfg_src {
        ImPtDetectCfgSource::ChangedSavedToDisk(src) => {
            // Retrieve the saved preferences
            let (app_info, prefs_key) = src;
            match ImPtDetectCfg::load(app_info, prefs_key) {
                Ok(cfg) => cfg,
                Err(e) => {
                    info!(
                        "Failed loading image detection config ({}), using defaults.",
                        e
                    );
                    default_im_pt_detect()
                }
            }
        }
        ImPtDetectCfgSource::ChangesNotSavedToDisk(cfg) => cfg.clone(),
    };

    let (mainbrain_session, trigger_type) = match braid_info {
        Some(bi) => (
            Some(bi.mainbrain_session),
            Some(bi.config_from_braid.trig_config),
        ),
        None => (None, None),
    };

    // Setup PTP and let clocks converge prior to starting acquisition.
    if let Some(TriggerType::PtpSync(ptpcfg)) = &trigger_type {
        let mut clock_sync_threshold_usecs = None;
        if let Some(period_usec) = ptpcfg.periodic_signal_period_usec {
            let period_usec_int = period_usec as i64;
            if period_usec - period_usec_int as f64 > 1.0 {
                eyre::bail!("period cannot be specified to sub-microsecond precision");
            }
            clock_sync_threshold_usecs = Some(period_usec_int / 2);
            if cam.feature_float(PERIOD_NAME)? != period_usec {
                cam.feature_float_set(PERIOD_NAME, period_usec)?;
                tracing::debug!(
                    "Set camera parameter {PERIOD_NAME} to {period_usec} microseconds."
                );
            }
        };
        if !cam.feature_bool("PtpEnable")? {
            tracing::debug!("Enabling PTP.");
            cam.feature_bool_set("PtpEnable", true)?;
        }
        // If period not set, default to 1 millisecond.
        let clock_sync_threshold_nanos = clock_sync_threshold_usecs.unwrap_or(1_000) * 1_000;
        loop {
            cam.command_execute("PtpDataSetLatch", true)?;
            let ptp_offset_from_master = cam.feature_int("PtpOffsetFromMaster")?;
            // Basler docs: "PtpOffsetFromMaster: Indicates the estimated
            // temporal offset between the master clock and the clock of the
            // current PTP device in ticks (1 tick = 1 nanosecond)."
            tracing::debug!("PTP clock offset {ptp_offset_from_master} nanoseconds.");
            if ptp_offset_from_master.abs() < clock_sync_threshold_nanos {
                // if within threshold from master, call it good enough.
                break;
            }
            tracing::info!(
                "PTP clock offset {ptp_offset_from_master} nanoseconds (threshold \
                        {clock_sync_threshold_nanos}), waiting 1 second for convergence."
            );
            tokio::time::sleep(std::time::Duration::from_millis(1000)).await;
        }
        tracing::info!(
            "PTP clock within threshold {clock_sync_threshold_nanos} nanoseconds from master."
        );

        if cam.feature_enum("TriggerMode")? != "On" {
            cam.feature_enum_set("TriggerMode", "On")?;
        }
        if cam.feature_enum("TriggerSource")? != "PeriodicSignal1" {
            cam.feature_enum_set("TriggerSource", "PeriodicSignal1")?;
        }
    };

    // Start the camera.
    cam.acquisition_start()?;
    // Buffer 20 frames to be processed before dropping them.
    let (tx_frame, rx_frame) = tokio::sync::mpsc::channel::<Msg>(20);
    let tx_frame2 = tx_frame.clone();

    // Get initial frame to determine width, height and pixel_format.
    debug!("  started acquisition, waiting for first frame");
    let frame = cam.next_frame()?;
    info!(
        "  acquired first frame: {}x{}",
        frame.width(),
        frame.height()
    );

    #[cfg(target_os = "linux")]
    let v4l_out_stream = {
        let frame_image = frame.image.borrow();
        use machine_vision_formats::Stride;
        if let Some(v4l_device) = &args.v4l2loopback {
            use machine_vision_formats::ImageData;
            let frame = frame_image
                .as_static::<formats::pixel_format::Mono8>()
                .ok_or_else(|| {
                    eyre::eyre!(
                        "Currently unsupported pixel format for v4l2loopback: {:?}",
                        frame.pixel_format()
                    )
                })?;
            tracing::info!("Using v4l2loopback device {}", v4l_device.display());
            let out = v4l::device::Device::with_path(v4l_device).with_context(|| {
                format!("opening V4L2 loopback device {}", v4l_device.display())
            })?;
            let source_fmt = v4l::format::Format {
                width: frame.width(),
                height: frame.height(),
                stride: frame.stride().try_into()?,
                field_order: v4l::format::field::FieldOrder::Progressive,
                flags: 0.into(),
                size: u32::try_from(frame.stride())? * frame.height(),
                quantization: v4l::format::quantization::Quantization::FullRange,
                transfer: v4l::format::transfer::TransferFunction::None,
                fourcc: v4l::format::fourcc::FourCC::new(b"GREY"),
                colorspace: v4l::format::colorspace::Colorspace::RAW,
            };
            tracing::info!("Setting v4l2loopback format: {:?}", source_fmt);
            v4l::video::Output::set_format(&out, &source_fmt)?;

            let mut v4l_out_stream =
                v4l::io::mmap::stream::Stream::new(&out, v4l::buffer::Type::VideoOutput)?;

            let (buf_out, buf_out_meta) = v4l::io::traits::OutputStream::next(&mut v4l_out_stream)?;
            let buf_in = frame.image_data();
            let bytesused = buf_in.len().try_into()?;

            let buf_out = &mut buf_out[0..buf_in.len()];
            buf_out.copy_from_slice(buf_in);
            buf_out_meta.field = 0;
            buf_out_meta.bytesused = bytesused;
            Some(v4l_out_stream)
        } else {
            None
        }
    };

    let (firehose_tx, firehose_rx) = tokio::sync::mpsc::channel::<AnnotatedFrame>(5);

    // Put first frame in channel.
    firehose_tx
        .send(AnnotatedFrame {
            frame: frame.image.clone(),
            found_points: vec![],
            valid_display: None,
            annotations: vec![],
        })
        .await
        .unwrap();
    // .map_err(|e| anhow::anyhow!("failed to send frame"))?;

    let image_width = frame.width();
    let image_height = frame.height();

    let current_image_png = frame
        .image
        .borrow()
        .to_encoded_buffer(convert_image::EncoderOptions::Png)?;

    // If we have a session with mainbrain, create a channel that collects
    // messages from within Strand Cam to forward to mainbrain and create the
    // forwarding future. If we don't have a session, just create a dummy future
    // that never resolves.
    let (first_msg_tx, forward_to_mainbrain_fut): (_, Pin<Box<dyn Future<Output = _>>>) = {
        if let Some(mainbrain_session) = mainbrain_session {
            let (tx, rx) = FirstMsgForced::channel(10);
            let fut = forward_to_mainbrain(rx, mainbrain_session);
            (Some(tx), Box::pin(fut))
        } else {
            (None, Box::pin(std::future::pending()))
        }
    };

    const PERIOD_NAME: &str = "BslPeriodicSignalPeriod";

    let mut local_remote = Vec::new();
    let mut local_time0 = None;
    let mut cam_time0 = None;
    let mut device_clock_model = None;

    if trigger_type == Some(TriggerType::DeviceTimestamp) {
        // Attempt to relate camera timestamps to our clock
        tracing::info!("Reading camera timestamps to fit initial clock model.");

        let n_pts = 5;
        let mut tmp_debug_device_timestamp = None;
        for i in 0..n_pts {
            let (local, cam_time) = measure_times(&cam)?;
            tmp_debug_device_timestamp.get_or_insert(cam_time);
            let local_time_nanos = braid_types::PtpStamp::try_from(local).unwrap().get();
            local_time0.get_or_insert(local_time_nanos);
            let cam_time_ts = braid_types::PtpStamp::new(cam_time.try_into().unwrap()).get();
            cam_time0.get_or_insert(cam_time_ts);

            let this_local_time0 = local_time0.as_ref().unwrap();
            let this_cam_time0 = cam_time0.as_ref().unwrap();
            // dbg!(&local_time_nanos);
            // dbg!(&local_time_secs);
            let local_elapsed_nanos = local_time_nanos - this_local_time0;
            let device_elapsed_nanos = cam_time_ts - this_cam_time0;
            local_remote.push((device_elapsed_nanos as f64, local_elapsed_nanos as f64));
            // local_remote.push((cam_time_ts as f64, local_ts as f64));
            if i < n_pts - 1 {
                tokio::time::sleep(std::time::Duration::from_millis(1000)).await;
            }
        }
        let (gain, offset, residuals) = clock_model::fit_time_model(&local_remote)?;
        dbg!((gain, offset, residuals));

        let cm = strand_cam_bui_types::ClockModel {
            gain,
            offset,
            residuals,
            n_measurements: local_remote.len().try_into().unwrap(),
        };

        let device_timestamp: u64 = tmp_debug_device_timestamp.unwrap().try_into().unwrap();
        let this_cam_time0 = cam_time0.as_ref().unwrap();
        let device_elapsed_nanos = device_timestamp - this_cam_time0;
        let local_estimate_elapsed_nanos: f64 = (device_elapsed_nanos as f64) * cm.gain + cm.offset;

        dbg!((local_estimate_elapsed_nanos, device_timestamp, &cm));
        device_clock_model = Some(cm);
    }

    let local_and_cam_time0 = if let Some(ct0) = cam_time0 {
        let local_time0 = local_time0.as_ref().unwrap();
        Some((*local_time0, ct0))
    } else {
        None
    };

    let camera_periodic_signal_period_usec = {
        match cam.feature_float(PERIOD_NAME) {
            Ok(value) => {
                tracing::debug!("Camera parameter {PERIOD_NAME}: {value} microseconds");
                Some(value)
            }
            Err(e) => {
                tracing::debug!("Could not read feature {PERIOD_NAME}: {e}");
                None
            }
        }
    };

    let (cam_args_tx, cam_args_rx) = tokio::sync::mpsc::channel(100);
    let (led_box_tx_std, led_box_rx) = tokio::sync::mpsc::channel(20);

    let led_box_heartbeat_update_arc = Arc::new(RwLock::new(None));

    let (gain_min, gain_max) = feature_or(cam.gain_range(), (0.0, 0.0))?;
    let gain_ranged = RangedValue {
        name: "gain".into(),
        unit: "dB".into(),
        min: gain_min,
        max: gain_max,
        current: feature_or(cam.gain(), 0.0)?,
    };
    let (exposure_min, exposure_max) = feature_or(cam.exposure_time_range(), (0.0, 0.0))?;
    let exposure_ranged = RangedValue {
        name: "exposure time".into(),
        unit: "μsec".into(),
        min: exposure_min,
        max: exposure_max,
        current: feature_or(cam.exposure_time(), 0.0)?,
    };
    let gain_auto = cam.gain_auto().ok();
    let exposure_auto = cam.exposure_auto().ok();

    let mut frame_rate_limit = if frame_rate_limit_supported {
        let (min, max) = cam.acquisition_frame_rate_range()?;
        Some(RangedValue {
            name: "frame rate".into(),
            unit: "Hz".into(),
            min,
            max,
            current: cam.acquisition_frame_rate()?,
        })
    } else {
        None
    };

    let current_cam_settings_extension = settings_file_ext.to_string();

    // Load the persistent secret once: it both mints the self-expiring access
    // token in `start_listener` and validates it in the auth layer below.
    let persistent_secret = http_router::load_persistent_secret(args.secret.clone())?;

    let (listener, http_camserver_info) =
        braid_types::start_listener(&strand_cam_bui_http_address_string, &persistent_secret)
            .await?;
    let listen_addr = listener.local_addr()?;

    let mut transmit_msg_tx = None;
    if let Some(first_msg_tx) = first_msg_tx {
        let new_cam_data = braid_types::RegisterNewCamera {
            raw_cam_name: raw_cam_name.clone(),
            http_camserver_info: Some(BuiServerInfo::Server(http_camserver_info.clone())),
            cam_settings_data: Some(braid_types::UpdateCamSettings {
                current_cam_settings_buf: settings_on_start,
                current_cam_settings_extension: settings_file_ext,
            }),
            current_image_png: current_image_png.into(),
            camera_periodic_signal_period_usec,
        };

        // Get the generic sender back.
        transmit_msg_tx = Some(first_msg_tx.send_first_msg(new_cam_data).await?);
        tracing::info!("Registered camera with Braid.");
    }

    if force_camera_sync_mode {
        cam.start_default_external_triggering().unwrap();
        if let Some(transmit_msg_tx) = &transmit_msg_tx {
            send_cam_settings_to_braid(
                &cam.node_map_save()?,
                transmit_msg_tx,
                &current_cam_settings_extension,
                &raw_cam_name,
            )
            .await?;
        }
    }

    if camera_settings_filename.is_none()
        && let StartSoftwareFrameRateLimit::Enable(fps_limit) = &software_limit_framerate
    {
        // Set the camera.
        cam.set_software_frame_rate_limit(*fps_limit).unwrap();
        // Store the values we set.
        if let Some(ref mut ranged) = frame_rate_limit {
            ranged.current = cam.acquisition_frame_rate()?;
        } else {
            panic!("cannot set software frame rate limit");
        }
        frame_rate_limit_enabled = cam.acquisition_frame_rate_enable()?;
    }

    let trigger_mode = feature_or(cam.trigger_mode(), ci2::TriggerMode::Off)?;
    let trigger_selector = feature_or(cam.trigger_selector(), ci2::TriggerSelector::FrameStart)?;
    debug!("  got camera values");

    #[cfg(feature = "flydra_feat_detect")]
    let camera_cfg = CameraCfgFview2_0_26 {
        vendor: cam.vendor().into(),
        model: cam.model().into(),
        serial: cam.serial().into(),
        width: cam.width()?,
        height: cam.height()?,
    };

    #[cfg(feature = "flydratrax")]
    let kalman_tracking_config = {
        if let ImPtDetectCfgSource::ChangedSavedToDisk(ref src) = tracker_cfg_src {
            // Retrieve the saved preferences
            let (app_info, _im_pt_detect_prefs_key) = src;
            match KalmanTrackingConfig::load(app_info, KALMAN_TRACKING_PREFS_KEY) {
                Ok(cfg) => cfg,
                Err(e) => {
                    info!(
                        "Failed loading kalman tracking config ({}), using defaults.",
                        e
                    );
                    KalmanTrackingConfig::default()
                }
            }
        } else {
            panic!("flydratrax requires saving changes to disk");
        }
    };

    #[cfg(not(feature = "flydratrax"))]
    let kalman_tracking_config = KalmanTrackingConfig::default();

    #[cfg(feature = "flydratrax")]
    let led_program_config = {
        if let ImPtDetectCfgSource::ChangedSavedToDisk(ref src) = tracker_cfg_src {
            // Retrieve the saved preferences
            let (app_info, _im_pt_detect_prefs_key) = src;
            match LedProgramConfig::load(app_info, LED_PROGRAM_PREFS_KEY) {
                Ok(cfg) => cfg,
                Err(e) => {
                    info!("Failed loading LED config ({}), using defaults.", e);
                    LedProgramConfig::default()
                }
            }
        } else {
            panic!("flydratrax requires saving changes to disk");
        }
    };
    #[cfg(not(feature = "flydratrax"))]
    let led_program_config = LedProgramConfig::default();

    let cuda_devices = match nvenc::Dynlibs::new() {
        Ok(libs) => {
            match nvenc::NvEnc::new(&libs) {
                Ok(nv_enc) => {
                    let n = nv_enc.cuda_device_count()?;
                    let r: Result<Vec<String>> = (0..n)
                        .map(|i| {
                            let dev = nv_enc.new_cuda_device(i)?;
                            Ok(dev.name().map_err(nvenc::NvEncError::from)?)
                        })
                        .collect();
                    r?
                }
                Err(e) => {
                    info!(
                        "CUDA and nvidia-encode libraries loaded, but \
                        error during initialization: {}",
                        e,
                    );
                    // empty vector
                    Vec::new()
                }
            }
        }
        Err(e) => {
            // no cuda library, no libs
            info!("CUDA and nvidia-encode libraries not loaded: {}", e);
            // empty vector
            Vec::new()
        }
    };
    let mp4_cuda_device = if !cuda_devices.is_empty() {
        cuda_devices[0].as_str()
    } else {
        ""
    }
    .into();

    #[cfg(not(feature = "fiducial"))]
    let apriltag_state = None;

    #[cfg(feature = "fiducial")]
    let apriltag_state = Some(ApriltagState::default());

    let im_ops_state = ImOpsState::default();

    #[cfg(feature = "flydra_feat_detect")]
    let has_image_tracker_compiled = true;

    #[cfg(not(feature = "flydra_feat_detect"))]
    let has_image_tracker_compiled = false;

    let is_braid = match &args.standalone_or_braid {
        StandaloneOrBraid::Braid(_) => true,
        StandaloneOrBraid::Standalone(_) => false,
    };

    // -----------------------------------------------
    // Check if we can use nv h264 and, if so, set that as default.

    let ffmpeg_version = match ffmpeg_writer::ffmpeg_version() {
        Ok(ffmpeg_version) => Some(ffmpeg_version),
        Err(err) => {
            tracing::warn!("Could not identify ffmpeg version. {err}");
            None
        }
    };

    let is_nvenc_functioning = test_nvenc_save(frame.image.borrow())?;

    let mp4_codec = match is_nvenc_functioning {
        true => CodecSelection::H264Nvenc,
        // Default to ffmpeg libx264 (shown in the browser as "ffmpeg -c:v
        // libx264"). Must exactly match an entry in the `CodecSelection`
        // `EnumIter` list so the frontend selects it as an available codec.
        false => CodecSelection::Ffmpeg(FfmpegCodecArgs {
            codec: Some("libx264".to_string()),
            ..Default::default()
        }),
    };

    #[cfg(target_os = "macos")]
    let is_videotoolbox_functioning = true;

    #[cfg(not(target_os = "macos"))]
    let is_videotoolbox_functioning = false;

    // -----------------------------------------------

    let mp4_filename_template = args
        .mp4_filename_template
        .replace("{CAMNAME}", raw_cam_name.as_str());
    let fmf_filename_template = args
        .fmf_filename_template
        .replace("{CAMNAME}", raw_cam_name.as_str());
    let ufmf_filename_template = args
        .ufmf_filename_template
        .replace("{CAMNAME}", raw_cam_name.as_str());

    #[cfg(feature = "fiducial")]
    let format_str_apriltag_csv = args
        .apriltag_csv_filename_template
        .replace("{CAMNAME}", use_camera_name);

    #[cfg(not(feature = "fiducial"))]
    let format_str_apriltag_csv = "".into();

    #[cfg(feature = "flydratrax")]
    let has_flydratrax_compiled = true;

    #[cfg(not(feature = "flydratrax"))]
    let has_flydratrax_compiled = false;

    let shared_store = ChangeTracker::new(StoreType {
        is_braid,
        ffmpeg_version,
        is_nvenc_functioning,
        is_videotoolbox_functioning,
        is_recording_mp4: None,
        is_recording_fmf: None,
        is_recording_ufmf: None,
        format_str_apriltag_csv,
        format_str_mp4: mp4_filename_template,
        format_str: fmf_filename_template,
        format_str_ufmf: ufmf_filename_template,
        camera_name: cam.name().into(),
        camera_gamma,
        recording_filename: None,
        mp4_bitrate: Default::default(),
        mp4_codec,
        mp4_max_framerate: Default::default(),
        mp4_cuda_device,
        gain: gain_ranged,
        gain_auto,
        exposure_time: exposure_ranged,
        exposure_auto,
        frame_rate_limit_enabled,
        frame_rate_limit,
        trigger_mode,
        trigger_selector,
        image_width,
        image_height,
        is_doing_object_detection: false,
        measured_fps: 0.0,
        is_saving_im_pt_detect_csv: None,
        has_image_tracker_compiled,
        im_pt_detect_cfg: im_pt_detect_cfg.clone(),
        has_flydratrax_compiled,
        kalman_tracking_config,
        led_program_config,
        led_box_device_lost: false,
        led_box_device_state: None,
        led_box_device_path: args.led_box_device_path.clone(),
        #[cfg(feature = "checkercal")]
        has_checkercal_compiled: true,
        #[cfg(not(feature = "checkercal"))]
        has_checkercal_compiled: false,
        checkerboard_data: strand_cam_storetype::CheckerboardCalState::default(),
        checkerboard_save_debug: None,
        post_trigger_buffer_size: 0,
        cuda_devices,
        apriltag_state,
        im_ops_state,
        had_frame_processing_error: false,
        camera_calibration: None,
        version_update: None,
    });

    let frame_processing_error_state = Arc::new(RwLock::new(FrameProcessingErrorState::default()));

    // let mut config = get_default_config();
    // config.cookie_name = "strand-camclient".to_string();

    let mut shared_store_changes_rx = shared_store.get_changes(1);

    // A channel for the data sent from the client browser.
    let (firehose_callback_tx, firehose_callback_rx) = tokio::sync::mpsc::channel(10);

    let callback_senders = StrandCamCallbackSenders {
        cam_args_tx: cam_args_tx.clone(),
        firehose_callback_tx,
        led_box_tx_std: led_box_tx_std.clone(),
        tx_frame: tx_frame.clone(),
    };

    let (tx_new_connection, rx_new_connection) = tokio::sync::mpsc::channel(10);

    let shared_state = Arc::new(RwLock::new(shared_store));
    let shared_store_arc = shared_state.clone();

    // Create our app state.
    let app_state = StrandCamAppState {
        cam_name: cam.name().to_string(),
        event_broadcaster: Default::default(),
        callback_senders,
        tx_new_connection,
        shared_store_arc,
        bui_server_info: http_camserver_info.clone(),
        persistent_secret: persistent_secret.clone(),
    };

    let shared_store_arc = shared_state.clone();

    // This future will send state updates to all connected event listeners.
    let event_broadcaster = app_state.event_broadcaster.clone();
    // A separate handle for the command task, which broadcasts a final "quit"
    // event to all clients during shutdown.
    let quit_event_broadcaster = app_state.event_broadcaster.clone();
    let send_updates_future = async move {
        while let Some((_prev_state, next_state)) = shared_store_changes_rx.next().await {
            let chunk = to_event_chunk(&next_state);
            event_broadcaster.broadcast_frame(chunk).await;
        }
    };

    let trusted_networks = braid_types::parse_trusted_networks(&args.trusted_networks)?;
    let router = http_router::build_http_router(
        persistent_secret,
        trusted_networks,
        http_camserver_info.token(),
        app_state,
    )?;

    // create future for our app
    let http_serve_future = {
        use std::future::IntoFuture;
        axum::serve(
            listener,
            router.into_make_service_with_connect_info::<SocketAddr>(),
        )
        .into_future()
    };

    let urls = strand_bui_backend_session::build_urls(&http_camserver_info)?;

    #[cfg(feature = "eframe-gui")]
    {
        // Loop until GUI from other thread is available.
        loop {
            {
                // scope for holding lock
                let mut my_guard = gui_singleton.lock().unwrap();

                // http_camserver_info
                // Set URL
                my_guard.url = Some(format!("{}", urls[0]));

                // Ensure URL is drawn
                if let Some(ctx_ref) = my_guard.ctx.as_ref() {
                    ctx_ref.request_repaint();
                    // We have GUI, exit wait loop.
                    break;
                }
            }
            // Wait a bit and check if GUI has launched again.
            tokio::time::sleep(std::time::Duration::from_millis(10)).await;
        }
    }

    #[cfg_attr(not(feature = "eframe-gui"), expect(clippy::let_unit_value))]
    let _ = gui_singleton;

    // Display where we are listening.
    if is_braid {
        debug!("Strand Cam listening at {listen_addr}");
    } else {
        info!("Strand Cam listening at {listen_addr}");

        for url in urls.iter() {
            info!(" * predicted URL {url}");
            if !braid_types::is_loopback(url) {
                println!("QR code for {url}");
                display_qr_url(&format!("{url}"))?;
            }
        }
    }

    #[cfg(feature = "checkercal")]
    let collected_corners_arc: CollectedCornersArc = Arc::new(RwLock::new(Vec::new()));

    let frame_process_task_fut = {
        #[cfg(feature = "flydra_feat_detect")]
        let csv_save_dir = args.csv_save_dir.clone();

        #[cfg(feature = "flydratrax")]
        let model_server_addr = args.model_server_addr;

        #[cfg(feature = "flydratrax")]
        let led_box_tx_std = led_box_tx_std.clone();
        #[cfg(feature = "flydratrax")]
        let http_camserver_info2 = http_camserver_info.clone();
        let led_box_heartbeat_update_arc2 = led_box_heartbeat_update_arc.clone();
        #[cfg(feature = "flydratrax")]
        let model_server_data_tx = {
            info!("send_pose server at {model_server_addr}");
            let (model_server_data_tx, data_rx) = tokio::sync::mpsc::channel(50);
            let model_server_future = flydra2::new_model_server(data_rx, model_server_addr);
            tokio::spawn(model_server_future);
            model_server_data_tx
        };

        let cam_name2 = raw_cam_name.clone();
        frame_process_task(
            #[cfg(feature = "flydratrax")]
            model_server_data_tx,
            cam_name2,
            #[cfg(feature = "flydra_feat_detect")]
            camera_cfg,
            #[cfg(feature = "flydra_feat_detect")]
            image_width,
            #[cfg(feature = "flydra_feat_detect")]
            image_height,
            rx_frame,
            #[cfg(feature = "flydra_feat_detect")]
            im_pt_detect_cfg,
            #[cfg(feature = "flydra_feat_detect")]
            std::path::Path::new(&csv_save_dir).to_path_buf(),
            firehose_tx,
            #[cfg(feature = "flydratrax")]
            led_box_tx_std,
            #[cfg(feature = "flydratrax")]
            http_camserver_info2,
            transmit_msg_tx.clone(),
            camdata_udp_addr,
            led_box_heartbeat_update_arc2,
            #[cfg(feature = "checkercal")]
            collected_corners_arc.clone(),
            #[cfg(feature = "flydratrax")]
            &args,
            #[cfg(feature = "flydra_feat_detect")]
            acquisition_duration_allowed_imprecision_msec,
            #[cfg(feature = "flydra_feat_detect")]
            app_name,
            device_clock_model,
            local_and_cam_time0,
            trigger_type,
            #[cfg(target_os = "linux")]
            v4l_out_stream,
            data_dir,
        )
    };
    debug!("frame_process_task spawned");

    tx_frame
        .send(Msg::Store(shared_store_arc.clone()))
        .await
        .unwrap();

    debug!("installing frame stream handler");

    // install frame handling
    let n_buffered_frames = 100;
    let frame_stream = cam.frames(n_buffered_frames)?;
    let cam_stream_future = cam_stream_task::run_cam_stream_task(
        frame_stream,
        tx_frame,
        shared_store_arc.clone(),
        frame_processing_error_state.clone(),
        transmit_msg_tx.clone(),
        raw_cam_name.clone(),
        send_image_to_braid_interval,
        gui_stuff2,
    );

    let do_version_check = match std::env::var_os("DISABLE_VERSION_CHECK") {
        Some(v) => &v == "0",
        None => true,
    };

    if do_version_check {
        let app_version: semver::Version = {
            let mut my_version = semver::Version::parse(env!("CARGO_PKG_VERSION")).unwrap();
            my_version.build = semver::BuildMetadata::new(env!("GIT_HASH").to_string().as_str())?;
            my_version
        };

        info!(
            "Welcome to {} {}. For more details \
            contact Andrew Straw <straw@bio.uni-freiburg.de>. This program will check for new \
            versions automatically. To disable printing this message and checking for new \
            versions, set the environment variable DISABLE_VERSION_CHECK=1.",
            app_name, app_version,
        );

        let store_for_version_check = shared_store_arc.clone();
        // Build the version-check client once and reuse it for every check.
        let checker = strand_version_check::VersionChecker::new();

        // Check now and every 30 minutes.
        let interval_stream = tokio::time::interval(std::time::Duration::from_secs(1800));
        let mut interval_stream = tokio_stream::wrappers::IntervalStream::new(interval_stream);

        let stream_future = async move {
            // The newest version this client knows about. Starts as our own
            // version and is advanced as the server reports newer ones, so each
            // new version is announced only once.
            let mut known_version = app_version;
            while interval_stream.next().await.is_some() {
                let user_agent = format!("{}/{}", app_name, known_version);
                if let Some(av) = checker.fetch("strand-cam", &user_agent).await
                    && av.version > known_version
                {
                    info!(
                        "New version of {} is available: {}. {}",
                        app_name, av.version, av.message
                    );
                    // Surface to every connected browser as a dismissible banner.
                    let update = strand_cam_storetype::VersionUpdate {
                        available: av.version.to_string(),
                        message: av.message,
                        url: av.url,
                    };
                    let mut tracker = store_for_version_check.write().unwrap();
                    tracker.modify(|store| store.version_update = Some(update));
                    known_version = av.version;
                }
            }
            debug!("version check future done {}:{}", file!(), line!());
        };
        tokio::spawn(Box::pin(stream_future));
        debug!("version check future spawned {}:{}", file!(), line!());
    }

    tokio::spawn(Box::pin(cam_stream_future));
    debug!("cam_stream_future future spawned {}:{}", file!(), line!());

    let cam_arg_future = {
        #[cfg(feature = "checkercal")]
        let cam_name2 = raw_cam_name.clone();

        cam_arg_task::run_cam_arg_task(
            cam,
            cam_args_rx,
            shared_store_arc.clone(),
            quit_event_broadcaster,
            frame_processing_error_state,
            transmit_msg_tx,
            current_cam_settings_extension,
            raw_cam_name,
            tx_frame2,
            #[cfg(feature = "flydra_feat_detect")]
            tracker_cfg_src,
            #[cfg(feature = "checkercal")]
            cam_name2,
            #[cfg(feature = "checkercal")]
            collected_corners_arc,
            #[cfg(feature = "checkercal")]
            image_width,
            #[cfg(feature = "checkercal")]
            image_height,
        )
    };

    let (launched_tx, mut launched_rx) = tokio::sync::watch::channel(());

    #[cfg(not(feature = "eframe-gui"))]
    let no_browser = args.no_browser;

    // Never launch browser automatically in GUI mode.
    #[cfg(feature = "eframe-gui")]
    let no_browser = true;

    if !no_browser {
        // Spawn a task which first waits for the Strand Cam webserver to be
        // ready and then itself opens a browser.
        let _launcher_task = tokio::spawn(async move {
            // Let the webserver start before opening browser.
            launched_rx.changed().await.unwrap();
            let url = format!("{}", urls[0]);
            let blocking_task = tokio::task::spawn_blocking(move || {
                info!("Opening browser at {}", url);
                match webbrowser::open(&url) {
                    Ok(_) => trace!("Browser opened"),
                    Err(e) => error!("Error opening brower: {:?}", e),
                };
                debug!("browser thread done {}:{}", file!(), line!());
            });
            blocking_task.await?;
            Ok::<_, eyre::Report>(())
        });
    }

    let firehose_task_join_handle = tokio::spawn(async {
        // The first thing this task does is pop a frame from firehose_rx, so we
        // should ensure there is one present.
        video_streaming::firehose_task(rx_new_connection, firehose_rx, firehose_callback_rx)
            .await
            .unwrap();
    });

    debug!("  running forever");

    led_box_task::run_led_box_task(
        led_box_tx_std,
        led_box_rx,
        led_box_heartbeat_update_arc,
        shared_store_arc,
    )
    .await?;
    // _dummy_tx is not dropped until after `select!` below. It will never send.
    let (_dummy_tx, dummy_rx) = tokio::sync::mpsc::channel(1);
    let mut quit_rx = match quit_rx {
        None => dummy_rx,
        Some(fut) => fut,
    };

    // Now run until first future returns, then exit.
    info!("Strand Cam launched.");
    launched_tx.send(())?;
    tokio::select! {
        res = http_serve_future => {res?},
        res = cam_arg_future => {res?},
        res = forward_to_mainbrain_fut => {res?},
        _ = send_updates_future => {},
        res = frame_process_task_fut => {res?},
        res = firehose_task_join_handle => {res?},
        _ = quit_rx.recv() => {},
    }
    info!("Strand Cam ending nicely. :)");
    // All other futures above are now dropped, thus cancelled.

    Ok(mymod)
}

fn measure_times<C>(cam: &C) -> Result<(chrono::DateTime<chrono::Utc>, i64)>
where
    C: ci2::Camera,
{
    let start = chrono::Utc::now();
    cam.command_execute("TimestampLatch", true)?;
    let remote = cam.feature_int("TimestampLatchValue")?;
    let stop = chrono::Utc::now();
    let max_err = stop - start;
    // assume symmetric delay
    let remote_offset_symmetric = max_err / 2;
    let remote_in_local = start + remote_offset_symmetric;
    tracing::debug!("Camera timestamp: {remote_in_local} {remote} {max_err}.");
    Ok((remote_in_local, remote))
}

async fn send_cam_settings_to_braid(
    cam_settings: &str,
    transmit_msg_tx: &tokio::sync::mpsc::Sender<braid_types::BraidHttpApiCallback>,
    current_cam_settings_extension: &str,
    raw_cam_name: &RawCamName,
) -> StdResult<(), tokio::sync::mpsc::error::SendError<braid_types::BraidHttpApiCallback>> {
    let current_cam_settings_buf = cam_settings.to_string();
    let current_cam_settings_extension = current_cam_settings_extension.to_string();
    let raw_cam_name = raw_cam_name.clone();
    let transmit_msg_tx = transmit_msg_tx.clone();

    let msg = braid_types::BraidHttpApiCallback::UpdateCamSettings(braid_types::PerCam {
        raw_cam_name,
        inner: braid_types::UpdateCamSettings {
            current_cam_settings_buf,
            current_cam_settings_extension,
        },
    });
    transmit_msg_tx.send(msg).await
}

fn bitrate_to_u32(br: &strand_cam_remote_control::BitrateSelection) -> Option<u32> {
    use strand_cam_remote_control::BitrateSelection::*;
    Some(match br {
        Bitrate500 => 500,
        Bitrate1000 => 1000,
        Bitrate2000 => 2000,
        Bitrate3000 => 3000,
        Bitrate4000 => 4000,
        Bitrate5000 => 5000,
        Bitrate10000 => 10000,
        BitrateUnlimited => return None,
    })
}

struct FinalMp4RecordingConfig {
    final_cfg: strand_cam_remote_control::RecordingConfig,
}

impl FinalMp4RecordingConfig {
    fn new(shared: &StoreType, creation_time: chrono::DateTime<chrono::Local>) -> Self {
        let mp4_codec = match shared.mp4_codec {
            CodecSelection::H264Nvenc => {
                let cuda_device = shared
                    .cuda_devices
                    .iter()
                    .position(|x| x == &shared.mp4_cuda_device)
                    .unwrap_or(0);
                let cuda_device = cuda_device.try_into().unwrap();
                Some(Mp4Codec::H264NvEnc(NvidiaH264Options {
                    bitrate: bitrate_to_u32(&shared.mp4_bitrate),
                    cuda_device,
                }))
            }
            CodecSelection::H264OpenH264 => {
                let preset = strand_cam_remote_control::OpenH264Preset::AllFrames;
                if shared.mp4_bitrate
                    != strand_cam_remote_control::BitrateSelection::BitrateUnlimited
                {
                    warn!("ignoring mp4 bitrate with OpenH264 codec");
                }
                Some(Mp4Codec::H264OpenH264(
                    strand_cam_remote_control::OpenH264Options {
                        debug: false,
                        preset,
                    },
                ))
            }
            _ => None,
        };
        let h264_metadata = {
            let mut h264_metadata =
                strand_cam_remote_control::H264Metadata::new("strand-cam", creation_time.into());
            h264_metadata.camera_name = Some(shared.camera_name.clone());
            h264_metadata.gamma = shared.camera_gamma;
            Some(h264_metadata)
        };
        let final_cfg = if let Some(codec) = mp4_codec {
            let final_cfg = Mp4RecordingConfig {
                codec,
                max_framerate: shared.mp4_max_framerate.clone(),
                h264_metadata,
            };
            strand_cam_remote_control::RecordingConfig::Mp4(final_cfg)
        } else {
            use strand_cam_remote_control::CodecSelection::*;
            let codec = match &shared.mp4_codec {
                H264Nvenc | H264OpenH264 => {
                    unreachable!();
                }
                Ffmpeg(args) => args.clone(),
            };
            strand_cam_remote_control::RecordingConfig::Ffmpeg(FfmpegRecordingConfig {
                codec_args: codec,
                max_framerate: shared.mp4_max_framerate.clone(),
                h264_metadata,
            })
        };
        FinalMp4RecordingConfig { final_cfg }
    }
}

fn to_eyre<T>(e: SendError<T>) -> eyre::Report {
    eyre!("SendError: {e} {e:?}")
}

#[cfg(test)]
mod tests {
    use super::*;

    use std::net::Ipv4Addr;

    // ---- Layer 1: `find_local_ip_for_remote` ----
    //
    // These exercise the real UDP-connect routing primitive. UDP `connect()`
    // sends no packets, so these do not require actual network connectivity,
    // only that the relevant route/interface exists. Cases that depend on
    // optional setup (IPv6, a non-loopback interface) skip rather than fail.

    #[test]
    fn local_ip_for_loopback_is_loopback() {
        let local = find_local_ip_for_remote(IpAddr::V4(Ipv4Addr::LOCALHOST))
            .expect("resolving local IP for IPv4 loopback should always succeed");
        assert!(
            local.is_loopback(),
            "expected loopback source for loopback remote, got {local}"
        );
    }

    #[test]
    fn local_ip_for_ipv6_loopback_is_loopback() {
        // Skip on hosts without IPv6 (some CI environments).
        if UdpSocket::bind(SocketAddr::new(IpAddr::V6(Ipv6Addr::UNSPECIFIED), 0)).is_err() {
            eprintln!("skipping: no IPv6 support on this host");
            return;
        }
        let local = find_local_ip_for_remote(IpAddr::V6(Ipv6Addr::LOCALHOST))
            .expect("resolving local IP for IPv6 loopback should succeed when IPv6 is present");
        assert!(
            local.is_loopback(),
            "expected loopback source for loopback remote, got {local}"
        );
    }

    /// Connecting to one of the machine's own non-loopback interface IPs makes
    /// the OS select that same IP as the source. This is the property that lets
    /// a single node simulate a "remote" Braid in a future integration test.
    #[test]
    fn local_ip_for_own_interface_is_that_interface() {
        // Find a non-loopback IPv4 address that is actually bindable on this
        // host (i.e. assigned to a local interface). `0` lets the OS pick a
        // free port; a successful bind proves the IP is local.
        let Some(local_iface_ip) = local_non_loopback_ipv4() else {
            eprintln!("skipping: no non-loopback IPv4 interface on this host");
            return;
        };
        let resolved = find_local_ip_for_remote(local_iface_ip)
            .expect("resolving local IP for an own interface IP should succeed");
        assert_eq!(
            resolved, local_iface_ip,
            "expected own interface IP {local_iface_ip} to resolve to itself, got {resolved}"
        );
    }

    /// Return a non-loopback IPv4 address assigned to this host, if any.
    ///
    /// Rather than enumerating interfaces (which needs a platform-specific
    /// crate), we probe a few common destinations and treat the resulting
    /// non-loopback source IP as a known-local interface address.
    fn local_non_loopback_ipv4() -> Option<IpAddr> {
        // Public IPs route via the default gateway interface (if one exists);
        // the documentation/TEST-NET ranges are used purely as routing targets,
        // no packets are sent.
        for probe in ["8.8.8.8", "192.0.2.1", "1.1.1.1"] {
            let remote: IpAddr = probe.parse().unwrap();
            if let Ok(local) = find_local_ip_for_remote(remote)
                && !local.is_loopback()
                && local.is_ipv4()
            {
                return Some(local);
            }
        }
        None
    }

    // ---- Layer 2: `braid_strand_cam_http_address` decision logic ----
    //
    // Pure logic, tested with an injected resolver so no sockets are involved.

    const LOOPBACK: IpAddr = IpAddr::V4(Ipv4Addr::LOCALHOST);
    const REMOTE: IpAddr = IpAddr::V4(Ipv4Addr::new(192, 168, 1, 10));

    fn resolver_ok(ip: IpAddr) -> impl FnOnce(IpAddr) -> std::io::Result<IpAddr> {
        move |_remote| Ok(ip)
    }

    fn resolver_err() -> impl FnOnce(IpAddr) -> std::io::Result<IpAddr> {
        |_remote| Err(std::io::Error::other("simulated resolver failure"))
    }

    #[test]
    fn loopback_braid_no_override_binds_loopback() {
        let addr = braid_strand_cam_http_address(LOOPBACK, None, resolver_ok(REMOTE));
        assert_eq!(addr, "127.0.0.1:0");
    }

    #[test]
    fn remote_braid_no_override_uses_resolved_local_ip() {
        let local = IpAddr::V4(Ipv4Addr::new(192, 168, 1, 20));
        let addr = braid_strand_cam_http_address(REMOTE, None, resolver_ok(local));
        assert_eq!(addr, "192.168.1.20:0");
    }

    #[test]
    fn remote_braid_resolver_failure_falls_back_to_loopback() {
        let addr = braid_strand_cam_http_address(REMOTE, None, resolver_err());
        assert_eq!(addr, "127.0.0.1:0");
    }

    #[test]
    fn override_is_used_verbatim_for_remote_braid() {
        // The override must win even though the resolver would return something
        // else; the resolver must not even be consulted.
        let addr = braid_strand_cam_http_address(REMOTE, Some("10.0.0.5:1234".to_string()), |_| {
            panic!("resolver must not be called when an override is present")
        });
        assert_eq!(addr, "10.0.0.5:1234");
    }

    #[test]
    fn override_is_used_verbatim_for_loopback_braid() {
        let addr =
            braid_strand_cam_http_address(LOOPBACK, Some("0.0.0.0:44444".to_string()), |_| {
                panic!("resolver must not be called when an override is present")
            });
        assert_eq!(addr, "0.0.0.0:44444");
    }
}