dovecot-2.2: lib-http server: Comment updates

[dovecot at dovecot.org]

details:   http://hg.dovecot.org/dovecot-2.2/rev/531aad735130
changeset: 17699:531aad735130
user:      Timo Sirainen <tss at iki.fi>
date:      Mon Aug 11 15:55:03 2014 +0300
description:
lib-http server: Comment updates

diffstat:

 src/lib-http/http-server-connection.c |   5 ++-
 src/lib-http/http-server.h            |  36 ++++++++++++++++++++++++++--------
 2 files changed, 30 insertions(+), 11 deletions(-)

diffs (80 lines):

diff -r e593dce9468d -r 531aad735130 src/lib-http/http-server-connection.c
--- a/src/lib-http/http-server-connection.c	Mon Aug 11 15:54:43 2014 +0300
+++ b/src/lib-http/http-server-connection.c	Mon Aug 11 15:55:03 2014 +0300
@@ -341,6 +341,7 @@
 		return TRUE;
 	}
 
+	/* Request payload is still being uploaded by the client */
 	return FALSE;
 }
 
@@ -438,13 +439,13 @@
 
 			conn->stats.request_count++;
 
-			/* handle request 
-			   req may be destroyed after this, so don't refer to it if ret > 0 */
 			http_server_request_ref(req);
 			T_BEGIN {
 				cont = http_server_connection_handle_request(conn, req);
 			} T_END;
 			if (!cont) {
+				/* connection closed or request body not read yet.
+				   the request may be destroyed now. */
 				http_server_request_unref(&req);
 				return;
 			}
diff -r e593dce9468d -r 531aad735130 src/lib-http/http-server.h
--- a/src/lib-http/http-server.h	Mon Aug 11 15:54:43 2014 +0300
+++ b/src/lib-http/http-server.h	Mon Aug 11 15:55:03 2014 +0300
@@ -38,10 +38,23 @@
 };
 
 struct http_server_callbacks {
-	/* Reference the server request. Before returning you must either send
-	   a response to the request or reference the request with
-	   http_server_request_ref() and unreference it later after sending
-	   the response. */
+	/* Handle the server request. All requests must be sent back a response.
+	   The response is sent either with http_server_request_fail*() or
+	   http_server_response_submit*(). For simple requests you can send the
+	   response back immediately. If you can't do that, you'll need to
+	   reference the request. Then the code flow usually goes like this:
+
+	   - http_server_request_set_destroy_callback(destroy_callback)
+	   - http_server_request_ref()
+	   - <do whatever is needed to handle the request>
+	   - http_server_response_create()
+	   - http_server_response_set_payload() can be used especially with
+	     istream-callback to create a large response without temp files.
+	   - http_server_response_submit() triggers the destroy_callback
+	     after it has finished sending the response and its payload.
+	   - In destroy_callback: http_server_request_unref() and any other
+	     necessary cleanup - the request handling is now fully finished.
+	*/
 	void (*handle_request)(void *context, struct http_server_request *req);
 	void (*handle_connect_request)(void *context,
 		struct http_server_request *req, struct http_url *target);
@@ -85,11 +98,16 @@
 void http_server_request_fail_close(struct http_server_request *req,
 	unsigned int status, const char *reason);
 
-/* Call the specified callback when HTTP request is destroyed. This always
-   happens only after the response and its payload is fully sent. (If request
-   headers aren't fully read, we never call the handle_request() callback.
-   The request body reading is the responsibility of the caller, which also
-   needs to handle its errors by sending a failure response.) */
+/* Call the specified callback when HTTP request is destroyed. This happens
+   after one of the following:
+
+   a) Response and its payload is fully sent
+   b) Response was submitted, but it couldn't be sent due to disconnection.
+   c) http_server_deinit() was called and the request was aborted
+
+   Note client disconnection before response is submitted isn't visible to this.
+   The request payload reading is the responsibility of the caller, which also
+   must handle the read errors by submitting a failure response. */
 void http_server_request_set_destroy_callback(struct http_server_request *req,
 					      void (*callback)(void *),
 					      void *context);