From 7326e9aadd93ed34ac714f039a81f309cac83db4 Mon Sep 17 00:00:00 2001
From: Eric Wong <e@80x24.org>
Date: Mon, 6 Sep 2021 12:58:01 +0000
Subject: [PATCH] lei_auth: diagram for current behavior

Before making potentially major changes, lets clarify readers'
understanding of how LeiAuth currently works.
---
 lib/PublicInbox/LeiAuth.pm | 31 ++++++++++++++++++++++++++++---
 1 file changed, 28 insertions(+), 3 deletions(-)

diff --git a/lib/PublicInbox/LeiAuth.pm b/lib/PublicInbox/LeiAuth.pm
index bbd713f0..3155d79b 100644
--- a/lib/PublicInbox/LeiAuth.pm
+++ b/lib/PublicInbox/LeiAuth.pm
@@ -3,18 +3,42 @@
 
 # Authentication worker for anything that needs auth for read/write IMAP
 # (eventually for read-only NNTP access)
+#
+# timelines
+# lei-daemon              |  LeiAuth worker #0      | other WQ workers
+# ----------------------------------------------------------
+# spawns all workers ---->[ workers all start and run ipc_atfork_child ]
+#                         | do_auth_atfork          | wq_worker_loop sleep
+#                         | # reads .netrc          |
+#                         | # queries git-credential|
+#                         | send net_merge_continue |
+#                         |         |               |
+#                         |         v               |
+# recv net_merge_continue <---------/               |
+#            |            |                         |
+#            v            |                         |
+# broadcast net_merge_all [ all workers (including LeiAuth worker #0) ]
+#                         [ LeiAuth worker #0 becomes just another WQ worker ]
+#                         |
+#                         | each worker sends net_merge_done1 to lei-daemon
+#                         |              |  | ... |
+#                         |              v  v     v
+# recv net_merge_done1 <--<-------<------/--/--<--/
+#
+# call net_merge_all_done ->-> do per-class defined actions
 package PublicInbox::LeiAuth;
 use strict;
 use v5.10.1;
 
 sub do_auth_atfork { # used by IPC WQ workers
 	my ($self, $wq) = @_;
-	return if $wq->{-wq_worker_nr} != 0;
+	return if $wq->{-wq_worker_nr} != 0; # only first worker calls this
 	my $lei = $wq->{lei};
 	my $net = $lei->{net};
-	eval {
+	eval { # fill auth info (may prompt user or read netrc)
 		my $mics = $net->imap_common_init($lei);
 		my $nn = $net->nntp_common_init($lei);
+		# broadcast successful auth info to lei-daemon:
 		$lei->{pkt_op_p}->pkt_do('net_merge_continue', $net) or
 				die "pkt_do net_merge_continue: $!";
 		$net->{mics_cached} = $mics if $mics;
@@ -33,6 +57,7 @@ sub net_merge_all { # called in wq worker via wq_broadcast
 	my ($wq, $net_new) = @_;
 	my $net = $wq->{lei}->{net};
 	%$net = (%$net, %$net_new);
+	# notify daemon we're ready
 	$wq->{lei}->{pkt_op_p}->pkt_do('net_merge_done1') or
 		die "pkt_op_do net_merge_done1: $!";
 }
@@ -40,7 +65,7 @@ sub net_merge_all { # called in wq worker via wq_broadcast
 # called by top-level lei-daemon when first worker is done with auth
 sub net_merge_continue {
 	my ($wq, $net_new) = @_;
-	$wq->wq_broadcast('net_merge_all', $net_new);
+	$wq->wq_broadcast('net_merge_all', $net_new); # pass to current workers
 }
 
 sub op_merge { # prepares PktOp->pair ops
-- 
2.44.0