Document TRANSFORM_READ internal-body bypass flow.

Add focused comments in HttpSM transform-read handling to explain why tunnel teardown, transform VC cleanup, response header seeding, and server session release are required before internal transfer.

Made-with: Cursor

Author: bryancall

src/proxy/http/HttpSM.cc

@@ -1687,24 +1687,31 @@ HttpSM::handle_api_return()
 
   switch (t_state.next_action) {
   case HttpTransact::StateMachineAction_t::TRANSFORM_READ: {
+    // A plugin has installed an internal response body (TSHttpTxnErrorBodySet()).
+    // In this branch we bypass transform streaming and switch to internal transfer.
     if (t_state.internal_msg_buffer && !t_state.api_server_request_body_set && t_state.hdr_info.server_response.valid()) {
       SMDbg(dbg_ctl_http, "plugin set internal body, bypassing response transform for internal transfer");
       t_state.api_info.cache_untransformed = true;
+      // If a tunnel was already set up for transform I/O, shut it down before we re-route.
       if (tunnel.is_tunnel_active()) {
         tunnel.kill_tunnel();
       }
+      // Drop transform VC table state because this path no longer drives transform reads.
       if (transform_info.entry != nullptr) {
         vc_table.cleanup_entry(transform_info.entry);
         transform_info.entry = nullptr;
       }
       transform_info.vc = nullptr;
+      // Some downstream paths still read client_response; seed it from transform_response when missing.
       if (t_state.hdr_info.client_response.valid() == 0 && t_state.hdr_info.transform_response.valid()) {
         t_state.hdr_info.client_response.create(HTTPType::RESPONSE);
         t_state.hdr_info.client_response.copy(&t_state.hdr_info.transform_response);
       }
+      // The server session is not needed for internal body transfer if it was never tunneled.
       if (server_entry != nullptr && server_entry->in_tunnel == false) {
         release_server_session();
       }
+      // Serve the plugin-provided body through the internal tunnel handler.
       setup_internal_transfer(&HttpSM::tunnel_handler);
     } else {
       HttpTunnelProducer *p = setup_transfer_from_transform();