Allowing protocol_propose hooks to be called with offers=NULL, clarifying semantics...

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1698116 13f79535-47bb-0310-9956-ffa450edef68

diff --git a/include/http_protocol.h b/include/http_protocol.h
index 846df2f05c8046cfa8198aef64551a3e334a17a2..06f32f12c939a38ff7920269cdbc6ce9e275037d 100644 (file)
--- a/include/http_protocol.h
+++ b/include/http_protocol.h
@@ -704,18 +704,27 @@ AP_DECLARE_HOOK(apr_port_t,default_port,(const request_rec *r))
 #define AP_PROTOCOL_HTTP1              "http/1.1"
 
 /**
- * Negotiate a possible protocol switch on the connection. The negotiation
- * may start without any request sent, in which case the request is NULL. Or
- * it may be triggered by the request received, e.g. through the "Upgrade"
- * header.
+ * Determine the list of protocols available for a connection/request. This may
+ * be collected with or without any request sent, in which case the request is 
+ * NULL. Or it may be triggered by the request received, e.g. through the 
+ * "Upgrade" header.
+ *
+ * This hook will be run whenever protocols are being negotiated (ALPN as
+ * one example). It may also be invoked at other times, e.g. when the server
+ * wants to advertise protocols it is capable of switching to.
  * 
  * The identifiers for protocols are taken from the TLS extension type ALPN:
  * https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xml
  *
- * If no protocols are added to the proposals, the server will always fallback
- * to "http/1.1" which is the default protocol for connections that Apache
- * handles. If the protocol selected from the proposals is the protocol
- * already in place, no "protocol_switch" will be invoked.
+ * If no protocols are added to the proposals, the server not perform any
+ * switch. If the protocol selected from the proposals is the protocol
+ * already in place, also no protocol switch will be invoked.
+ *
+ * The client may already have announced the protocols it is willing to
+ * accept. These will then be listed as offers. This parameter may also
+ * be NULL, indicating that offers from the client are not known and
+ * the hooks should propose all protocols that are valid for the
+ * current connection/request.
  *
  * All hooks are run, unless one returns an error. Proposals may contain
  * duplicates. The order in which proposals are added is usually ignored.
@@ -723,7 +732,8 @@ AP_DECLARE_HOOK(apr_port_t,default_port,(const request_rec *r))
  * @param c The current connection
  * @param r The current request or NULL
  * @param s The server/virtual host selected
- * @param offers A list of protocol identifiers offered by the client
+ * @param offers A list of protocol identifiers offered by the client or
+ *               NULL to indicated that the hooks are free to propose 
  * @param proposals The list of protocol identifiers proposed by the hooks
  * @return OK or DECLINED
  */

diff --git a/modules/http2/h2_switch.c b/modules/http2/h2_switch.c
index fd769833b0a7c4c85eaa4f42439cb54a81eb0003..46790ba4052a5b4d3adcdbd39cc599ed3c490687 100644 (file)
--- a/modules/http2/h2_switch.c
+++ b/modules/http2/h2_switch.c
@@ -105,9 +105,9 @@ static int h2_protocol_propose(conn_rec *c, request_rec *r,
     
     while (*protos) {
         /* Add all protocols we know (tls or clear) and that
-         * were offered as options for the switch. 
+         * are part of the offerings (if there have been any). 
          */
-        if (ap_array_index(offers, *protos) >= 0) {
+        if (!offers || ap_array_index(offers, *protos) >= 0) {
             ap_log_cerror(APLOG_MARK, APLOG_TRACE1, 0, c,
                           "proposing protocol '%s'", *protos);
             APR_ARRAY_PUSH(proposals, const char*) = *protos;