feat(ffi) expose kv & metrics shms through FFI

assets/INTERNAL_DIFFERENCES.md

@@ -0,0 +1,36 @@
+# Host SDK implementation differences
+
+This document lists internal discrepancies between ngx_wasm_module and other
+Proxy-Wasm host SDK implementations, e.g. Envoy, and it's meant to be used by
+ngx_wasm_module's developers rather than its users.
+
+## Table of Contents
+
+- [Metrics Prefixing](#metrics-prefixing)
+
+## Metrics Prefixing
+
+In ngx_wasm_module, Proxy-Wasm metric names are prefixed with `pw.filter_name.`,
+where `filter_name` represents the name assigned to the filter in which the
+metric is defined. A metric `m1` defined by a filter `f1` is represented
+internally as `pw.f1.m1`.
+
+Envoy, however, prefixes Proxy-Wasm metric names `wasmcustom.`. As such, a
+metric `m1` defined by a filter `f1` is represented internally as
+`wasmcustom.m1`.
+
+Proxy-Wasm filter developers don't need to be aware of such divergence as they
+never use the metric name to retrieve or update a metric's value.
+
+In fact, this difference shouldn't affect users at all, as long as host
+implementations expose metric names without their internal prefixing.
+
+Although Envoy will expose its internal prefixing in responses to the
+`/metrics` admin endpoint, it won't do it in responses to the
+`/metrics/prometheus` admin endpoint.
+
+ngx_wasm_module follows a similar pattern. Although its internal prefixing is
+exposed in metric names retrieved by its FFI, this interface is intended to be
+accessed by Kong Gateway developers only, not end-users. Kong Gateway in turn
+strips the internal prefixing before serializing the metrics in responses to the
+`/metrics` admin endpoint.

config

@@ -140,11 +140,10 @@ NGX_WASMX_DEPS="\
     $ngx_addon_dir/src/common/proxy_wasm/ngx_proxy_wasm.h \
     $ngx_addon_dir/src/common/proxy_wasm/ngx_proxy_wasm_maps.h \
     $ngx_addon_dir/src/common/proxy_wasm/ngx_proxy_wasm_properties.h \
-    $ngx_addon_dir/src/common/shm/ngx_wasm_shm.h \
-    $ngx_addon_dir/src/common/shm/ngx_wasm_shm_kv.h \
-    $ngx_addon_dir/src/common/shm/ngx_wasm_shm_queue.h \
-    $ngx_addon_dir/src/common/metrics/ngx_wa_metrics.h \
-    $ngx_addon_dir/src/common/metrics/ngx_wa_histogram.h"
+    $ngx_addon_dir/src/common/shm/ngx_wa_shm.h \
+    $ngx_addon_dir/src/common/shm/ngx_wa_shm_kv.h \
+    $ngx_addon_dir/src/common/shm/ngx_wa_shm_queue.h \
+    $ngx_addon_dir/src/common/metrics/ngx_wa_metrics.h"
 
 NGX_WASMX_SRCS="\
     $ngx_addon_dir/src/ngx_wasmx.c \
@@ -156,9 +155,9 @@ NGX_WASMX_SRCS="\
     $ngx_addon_dir/src/common/proxy_wasm/ngx_proxy_wasm_maps.c \
     $ngx_addon_dir/src/common/proxy_wasm/ngx_proxy_wasm_properties.c \
     $ngx_addon_dir/src/common/proxy_wasm/ngx_proxy_wasm_util.c \
-    $ngx_addon_dir/src/common/shm/ngx_wasm_shm.c \
-    $ngx_addon_dir/src/common/shm/ngx_wasm_shm_kv.c \
-    $ngx_addon_dir/src/common/shm/ngx_wasm_shm_queue.c \
+    $ngx_addon_dir/src/common/shm/ngx_wa_shm.c \
+    $ngx_addon_dir/src/common/shm/ngx_wa_shm_kv.c \
+    $ngx_addon_dir/src/common/shm/ngx_wa_shm_queue.c \
     $ngx_addon_dir/src/common/metrics/ngx_wa_metrics.c \
     $ngx_addon_dir/src/common/metrics/ngx_wa_histogram.c"