feat(auth): warn when sign-in falls back off the preferred port

Author: cloudbridgeuy

crates/llm_stream/src/auth/flow.rs

@@ -23,6 +23,9 @@ pub fn login(config_dir: &Path) -> Result<TokenSet> {
     let state = random_state();
 
     let listener = listener::bind()?;
+    if let Some(notice) = listener::fallback_notice(listener.port()?) {
+        eprintln!("{notice}");
+    }
     let redirect_uri = listener.redirect_uri()?;
 
     let url = oauth::authorize_url(&AuthorizeParams {

crates/llm_stream/src/auth/listener.rs

@@ -22,6 +22,24 @@ pub fn bind() -> Result<CallbackListener> {
     Ok(CallbackListener { listener })
 }
 
+/// The line an operator needs when the preferred port was taken.
+///
+/// `None` when the listener got port 1455. Otherwise a sentence naming the
+/// conflict, because the failure it predicts is otherwise unreadable: if
+/// `OpenAI` pins the redirect URI to 1455, the authorization server rejects the
+/// sign-in with a generic `invalid redirect_uri` and nothing on screen connects
+/// that to a port another process is holding.
+#[must_use]
+pub fn fallback_notice(port: u16) -> Option<String> {
+    (port != PREFERRED_PORT).then(|| {
+        format!(
+            "warning: port {PREFERRED_PORT} was busy, so sign-in is listening on port {port}. \
+             If the browser reports an invalid redirect URI, close whatever holds \
+             port {PREFERRED_PORT} (a running codex, or another llm-stream --login) and try again."
+        )
+    })
+}
+
 impl CallbackListener {
     pub fn port(&self) -> Result<u16> {
         Ok(self.listener.local_addr()?.port())
@@ -104,6 +122,23 @@ mod tests {
     use super::*;
     use std::io::Write;
 
+    #[test]
+    fn the_preferred_port_needs_no_notice() {
+        assert_eq!(fallback_notice(PREFERRED_PORT), None);
+    }
+
+    #[test]
+    fn a_fallback_port_names_both_ports_and_the_symptom() {
+        let Some(notice) = fallback_notice(54321) else {
+            panic!("a fallback port must produce a notice");
+        };
+        assert!(notice.contains("1455"), "got: {notice}");
+        assert!(notice.contains("54321"), "got: {notice}");
+        // Without this the operator sees an opaque browser error and has no
+        // reason to suspect a port conflict.
+        assert!(notice.contains("invalid redirect URI"), "got: {notice}");
+    }
+
     #[test]
     fn extracts_the_query_from_a_request_line() {
         assert_eq!(