docs: lua replace() function (#445)

Also clarify add() behavior.
Also sort HTTP filters and normalize names.

Signed-off-by: Matt Klein <mklein@lyft.com>

docs/root/configuration/http_filters/cors_filter.rst

@@ -1,7 +1,7 @@
 .. _config_http_filters_cors:
 
-CORS filter
-===========
+CORS
+====
 
 This is a filter which handles Cross-Origin Resource Sharing requests based on route or virtual host settings.
 For the meaning of the headers please refer to the pages below.

docs/root/configuration/http_filters/grpc_json_transcoder_filter.rst

@@ -1,7 +1,7 @@
 .. _config_http_filters_grpc_json_transcoder:
 
-gRPC-JSON transcoder filter
-===========================
+gRPC-JSON transcoder
+====================
 
 * gRPC :ref:`architecture overview <arch_overview_grpc>`
 * :ref:`v1 API reference <config_http_filters_grpc_json_transcoder_v1>`

docs/root/configuration/http_filters/grpc_web_filter.rst

@@ -1,7 +1,7 @@
 .. _config_http_filters_grpc_web:
 
-gRPC-Web filter
-====================
+gRPC-Web
+========
 
 * gRPC :ref:`architecture overview <arch_overview_grpc>`
 * :ref:`v1 API reference <config_http_filters_grpc_web_v1>`

docs/root/configuration/http_filters/http_filters.rst

@@ -8,14 +8,14 @@ HTTP filters
 
   buffer_filter
   cors_filter
-  fault_filter
-  gzip_filter
   dynamodb_filter
+  fault_filter
   grpc_http1_bridge_filter
   grpc_json_transcoder_filter
   grpc_web_filter
+  gzip_filter
   health_check_filter
+  lua_filter
   rate_limit_filter
   router_filter
-  lua_filter
   squash_filter

docs/root/configuration/http_filters/lua_filter.rst

@@ -284,6 +284,16 @@ add()
 Adds a header. *key* is a string that supplies the header key. *value* is a string that supplies
 the header value.
 
+.. attention::
+
+  Envoy treats certain headers specially. These are known as the O(1) or *inline* headers. The
+  list of inline headers can be found `here <https://github.com/envoyproxy/envoy/blob/6b6ce85a24094146c5c225f19b6ecc47b2ca84bf/include/envoy/http/header_map.h#L228>`_.
+  If an inline header is already present in the header map, *add()* will have no effect. If
+  attempting to *add()* a non-inline header, the additional header will be added so that the
+  resultant headers contains multiple header entries with the same name. Consider using the
+  *replace* function if want to replace a header with another value. Note also that we
+  understand this behavior is confusing and we may change it in a future release.
+
 get()
 ^^^^^
 
@@ -320,6 +330,16 @@ remove()
 
 Removes a header. *key* supplies the header key to remove.
 
+replace()
+^^^^^^^^^
+
+.. code-block:: lua
+
+  headers:add(key, value)
+
+Replaces a header. *key* is a string that supplies the header key. *value* is a string that supplies
+the header value. If the header does not exist, it is added as per the *add()* function.
+
 .. _config_http_filters_lua_buffer_wrapper:
 
 Buffer API