Add a bunch of new comments to explain connection_ap_rewrite{,_and_attach}

Also, do a little light refactoring to move some variable declarations
around and make a few things const

Also fix an obnoxious bug on checking for the DONE stream end reason.
It's not a flag; it's a possible value or a variable that needs to be
masked.