+
+ Dynamic Capture Example
+
+
+
+ Last Update: 29/05/2025
+
+
+
+
+
+ This example demonstrates how to use dynamic capture in Zoraxy plugins. Dynamic capture allows you to intercept requests based on real-time conditions, so you can program your plugin in a way that it can decided if it want to handle the request or not.
+
+
+
+
+
+ Notes: This example assumes you have already read Hello World and Stataic Capture Example.
+
+
+
+
+
+ Lets dive in!
+
+
+
+
+ 1. Create the plugin folder structure
+
+
+
+ Follow the same steps as the Hello World example to set up the plugin folder structure. Refer to the Hello World example sections 1 to 5 for details.
+
+
+
+
+ 2. Define Introspect
+
+
+
+ The introspect configuration specifies the dynamic capture sniff and ingress paths for your plugin.
+
+
+
runtimeCfg, err := plugin.ServeAndRecvSpec(&plugin.IntroSpect{
+ ID: "org.aroz.zoraxy.dynamic-capture-example",
+ Name: "Dynamic Capture Example",
+ Author: "aroz.org",
+ AuthorContact: "https://aroz.org",
+ Description: "This is an example plugin for Zoraxy that demonstrates how to use dynamic captures.",
+ URL: "https://zoraxy.aroz.org",
+ Type: plugin.PluginType_Router,
+ VersionMajor: 1,
+ VersionMinor: 0,
+ VersionPatch: 0,
+
+ DynamicCaptureSniff: "/d_sniff",
+ DynamicCaptureIngress: "/d_capture",
+
+ UIPath: UI_PATH,
+})
+if err != nil {
+ panic(err)
+}
+
+
+
+ Note the
+
+ DynamicCaptureSniff
+
+ and
+
+ DynamicCaptureIngress
+
+ . These paths define the sniffing and capturing behavior for dynamic requests. The sniff path is used to evaluate whether a request should be intercepted, while the ingress path handles the intercepted requests.
+
+
+
+
+ 3. Register Dynamic Capture Handlers
+
+
+
+ Dynamic capture handlers are used to process requests that match specific conditions.
+
+
+
pathRouter := plugin.NewPathRouter()
+pathRouter.SetDebugPrintMode(true)
+
+pathRouter.RegisterDynamicSniffHandler("/d_sniff", http.DefaultServeMux, func(dsfr *plugin.DynamicSniffForwardRequest) plugin.SniffResult {
+ if strings.HasPrefix(dsfr.RequestURI, "/foobar") {
+ fmt.Println("Accepting request with UUID: " + dsfr.GetRequestUUID())
+ return plugin.SniffResultAccpet
+ }
+ fmt.Println("Skipping request with UUID: " + dsfr.GetRequestUUID())
+ return plugin.SniffResultSkip
+})
+
+pathRouter.RegisterDynamicCaptureHandle("/d_capture", http.DefaultServeMux, func(w http.ResponseWriter, r *http.Request) {
+ w.WriteHeader(http.StatusOK)
+ w.Write([]byte("Welcome to the dynamic capture handler!\n\nRequest Info:\n"))
+ w.Write([]byte("Request URI: " + r.RequestURI + "\n"))
+ w.Write([]byte("Request Method: " + r.Method + "\n"))
+ w.Write([]byte("Request Headers:\n"))
+ headers := make([]string, 0, len(r.Header))
+ for key := range r.Header {
+ headers = append(headers, key)
+ }
+ sort.Strings(headers)
+ for _, key := range headers {
+ for _, value := range r.Header[key] {
+ w.Write([]byte(fmt.Sprintf("%s: %s\n", key, value)))
+ }
+ }
+})
+
+
+
+ The
+
+ RegisterDynamicSniffHandler
+
+ evaluates incoming requests, while the
+
+ RegisterDynamicCaptureHandle
+
+ processes the intercepted requests.
+
+
+
+ Sniffing Logic
+
+
+ If a module registered a dynamic capture path, Zoraxy will forward the request headers as
+
+ DynamicSniffForwardRequest
+
+ (
+
+ dsfr
+
+ ) object to all the plugins that is assigned to this tag. And in each of the plugins, a dedicated logic will take in the object and “think” if they want to handle the request. You can get the following information from the dsfr object by directly accessing the members of it.
+
+
type DynamicSniffForwardRequest struct {
+ Method string `json:"method"`
+ Hostname string `json:"hostname"`
+ URL string `json:"url"`
+ Header map[string][]string `json:"header"`
+ RemoteAddr string `json:"remote_addr"`
+ Host string `json:"host"`
+ RequestURI string `json:"request_uri"`
+ Proto string `json:"proto"`
+ ProtoMajor int `json:"proto_major"`
+ ProtoMinor int `json:"proto_minor"`
+}
+
+
+
+ You can also use the
+
+ GetRequest()
+
+ function to get the
+
+ *http.Request
+
+ object or
+
+ GetRequestUUID()
+
+ to get a
+
+ string
+
+ value that is a UUID corresponding to this request for later matching with the incoming, forwarded request.
+
+
+
+
+
+ Note that since all request will pass through the sniffing function in your plugin, do not implement any blocking logic in your sniffing function, otherwise this will slow down all traffic going through the HTTP proxy rule with the plugin enabled.
+
+
+
+
+
+ In the sniffing stage, you can choose to either return
+
+ ControlStatusCode_CAPTURED
+
+ , where Zoraxy will forward the request to your plugin
+
+ DynamicCaptureIngress
+
+ endpoint, or
+
+ ControlStatusCode_UNHANDLED
+
+ , where Zoraxy will pass on the request to the next dynamic handling plugin or if there are no more plugins to handle the routing, to the upstream server.
+
+
+
+ Capture Handling
+
+
+
+ The capture handling is where Zoraxy formally forward you the HTTP request the client is requesting. In this situation, you must response the request by properly handling the
+
+ http.Request
+
+ by writing to the
+
+ http.ResponseWriter
+
+ .
+
+
+
+
+ If there is a need to match the sniffing to the capture handling logic (Let say you want to design your plugin to run some kind of pre-processing before the actual request came in), you can use the
+
+ X-Zoraxy-Requestid
+
+ header in the HTTP request. This is the same UUID as the one you get from
+
+ dsfr.GetRequestUUID()
+
+ in the sniffing stage if they are the same request object on Zoraxy side.
+
+
+
+
+ The http request that Zoraxy forwards to the plugin capture handling endpoint contains header like these.
+
+
+
Request URI: /foobar/test
+Request Method: GET
+Request Headers:
+Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
+Accept-Encoding: gzip, deflate, br, zstd
+(more fileds)
+X-Forwarded-For: 127.0.0.1
+X-Forwarded-Proto: https
+X-Real-Ip: 127.0.0.1
+X-Zoraxy-Requestid: d00619b8-f39e-4c04-acd8-c3a6f55b1566
+
+
+
+ You can extract the
+
+ X-Zoraxy-Requestid
+
+ value from the request header and do your matching for implementing your function if needed.
+
+
+
+
+ 4. Render Debug UI
+
+
+
+ This UI is used help validate the management Web UI is correctly shown in Zoraxy webmin interface. You should implement the required management interface for your plugin here.
+
+
+
func RenderDebugUI(w http.ResponseWriter, r *http.Request) {
+ fmt.Fprint(w, "**Plugin UI Debug Interface**\n\n[Recv Headers] \n")
+ headerKeys := make([]string, 0, len(r.Header))
+ for name := range r.Header {
+ headerKeys = append(headerKeys, name)
+ }
+ sort.Strings(headerKeys)
+ for _, name := range headerKeys {
+ values := r.Header[name]
+ for _, value := range values {
+ fmt.Fprintf(w, "%s: %s\n", name, value)
+ }
+ }
+ w.Header().Set("Content-Type", "text/html")
+}
+
+
+
+ 5. Full Code
+
+
+
+ Here is the complete code for the dynamic capture example:
+
+
+
package main
+
+import (
+ "fmt"
+ "net/http"
+ "sort"
+ "strconv"
+ "strings"
+
+ plugin "example.com/zoraxy/dynamic-capture-example/mod/zoraxy_plugin"
+)
+
+const (
+ PLUGIN_ID = "org.aroz.zoraxy.dynamic-capture-example"
+ UI_PATH = "/debug"
+ STATIC_CAPTURE_INGRESS = "/s_capture"
+)
+
+func main() {
+ // Serve the plugin intro spect
+ // This will print the plugin intro spect and exit if the -introspect flag is provided
+ runtimeCfg, err := plugin.ServeAndRecvSpec(&plugin.IntroSpect{
+ ID: "org.aroz.zoraxy.dynamic-capture-example",
+ Name: "Dynamic Capture Example",
+ Author: "aroz.org",
+ AuthorContact: "https://aroz.org",
+ Description: "This is an example plugin for Zoraxy that demonstrates how to use dynamic captures.",
+ URL: "https://zoraxy.aroz.org",
+ Type: plugin.PluginType_Router,
+ VersionMajor: 1,
+ VersionMinor: 0,
+ VersionPatch: 0,
+
+ DynamicCaptureSniff: "/d_sniff",
+ DynamicCaptureIngress: "/d_capture",
+
+ UIPath: UI_PATH,
+
+ /*
+ SubscriptionPath: "/subept",
+ SubscriptionsEvents: []plugin.SubscriptionEvent{
+ */
+ })
+ if err != nil {
+ //Terminate or enter standalone mode here
+ panic(err)
+ }
+
+ // Setup the path router
+ pathRouter := plugin.NewPathRouter()
+ pathRouter.SetDebugPrintMode(true)
+
+ /*
+ Dynamic Captures
+ */
+ pathRouter.RegisterDynamicSniffHandler("/d_sniff", http.DefaultServeMux, func(dsfr *plugin.DynamicSniffForwardRequest) plugin.SniffResult {
+ //In this example, we want to capture all URI
+ //that start with /foobar and forward it to the dynamic capture handler
+ if strings.HasPrefix(dsfr.RequestURI, "/foobar") {
+ reqUUID := dsfr.GetRequestUUID()
+ fmt.Println("Accepting request with UUID: " + reqUUID)
+
+ // Print all the values of the request
+ fmt.Println("Method:", dsfr.Method)
+ fmt.Println("Hostname:", dsfr.Hostname)
+ fmt.Println("URL:", dsfr.URL)
+ fmt.Println("Header:")
+ for key, values := range dsfr.Header {
+ for _, value := range values {
+ fmt.Printf(" %s: %s\n", key, value)
+ }
+ }
+ fmt.Println("RemoteAddr:", dsfr.RemoteAddr)
+ fmt.Println("Host:", dsfr.Host)
+ fmt.Println("RequestURI:", dsfr.RequestURI)
+ fmt.Println("Proto:", dsfr.Proto)
+ fmt.Println("ProtoMajor:", dsfr.ProtoMajor)
+ fmt.Println("ProtoMinor:", dsfr.ProtoMinor)
+
+ // We want to handle this request, reply with aSniffResultAccept
+ return plugin.SniffResultAccpet
+ }
+
+ // If the request URI does not match, we skip this request
+ fmt.Println("Skipping request with UUID: " + dsfr.GetRequestUUID())
+ return plugin.SniffResultSkip
+ })
+ pathRouter.RegisterDynamicCaptureHandle("/d_capture", http.DefaultServeMux, func(w http.ResponseWriter, r *http.Request) {
+ // This is the dynamic capture handler where it actually captures and handle the request
+ w.WriteHeader(http.StatusOK)
+ w.Write([]byte("Welcome to the dynamic capture handler!"))
+
+ // Print all the request info to the response writer
+ w.Write([]byte("\n\nRequest Info:\n"))
+ w.Write([]byte("Request URI: " + r.RequestURI + "\n"))
+ w.Write([]byte("Request Method: " + r.Method + "\n"))
+ w.Write([]byte("Request Headers:\n"))
+ headers := make([]string, 0, len(r.Header))
+ for key := range r.Header {
+ headers = append(headers, key)
+ }
+ sort.Strings(headers)
+ for _, key := range headers {
+ for _, value := range r.Header[key] {
+ w.Write([]byte(fmt.Sprintf("%s: %s\n", key, value)))
+ }
+ }
+ })
+
+ http.HandleFunc(UI_PATH+"/", RenderDebugUI)
+ fmt.Println("Dynamic capture example started at http://127.0.0.1:" + strconv.Itoa(runtimeCfg.Port))
+ http.ListenAndServe("127.0.0.1:"+strconv.Itoa(runtimeCfg.Port), nil)
+}
+
+// Render the debug UI
+func RenderDebugUI(w http.ResponseWriter, r *http.Request) {
+ fmt.Fprint(w, "**Plugin UI Debug Interface**\n\n[Recv Headers] \n")
+
+ headerKeys := make([]string, 0, len(r.Header))
+ for name := range r.Header {
+ headerKeys = append(headerKeys, name)
+ }
+ sort.Strings(headerKeys)
+ for _, name := range headerKeys {
+ values := r.Header[name]
+ for _, value := range values {
+ fmt.Fprintf(w, "%s: %s\n", name, value)
+ }
+ }
+ w.Header().Set("Content-Type", "text/html")
+}
+
+
+
+
+ 6. Expected Output
+
+
+ To enable the plugin, add the plugin to one of the tags and assign the tag to your HTTP Proxy Rule. Here is an example of assigning the plugin to the “debug” tag and assigning it to a localhost loopback HTTP proxy rule.
+
+
+
+ When the plugin is running, requests matching the sniff conditions will be intercepted and processed by the dynamic capture handler.
+
+
+
+
+ If everything is correctly setup, you should see the following page when requesting any URL with prefix
+
+ (your_HTTP_proxy_rule_hostname)/foobar
+
+
+
+
+
+
+
+
+
+
+ Example terminal output for requesting
+
+ /foobar/*
+
+ :
+
+
+
[2025-05-30 20:44:26.142645] [plugin-manager] [system:info] [Dynamic Capture Example:22964] Request captured by dynamic sniff path: /d_sniff/
+[2025-05-30 20:44:26.142645] [plugin-manager] [system:info] [Dynamic Capture Example:22964] Header:
+[2025-05-30 20:44:26.142645] [plugin-manager] [system:info] [Dynamic Capture Example:22964] Method: GET
+[2025-05-30 20:44:26.142645] [plugin-manager] [system:info] [Dynamic Capture Example:22964] Hostname: a.localhost
+[2025-05-30 20:44:26.142645] [plugin-manager] [system:info] [Dynamic Capture Example:22964] URL: /foobar/test
+[2025-05-30 20:44:26.142645] [plugin-manager] [system:info] [Dynamic Capture Example:22964] Accepting request with UUID: 8c916c58-0d6a-4d11-a2f0-f29d3d984509
+[2025-05-30 20:44:26.143165] [plugin-manager] [system:info] [Dynamic Capture Example:22964] Sec-Fetch-Dest: document
+[2025-05-30 20:44:26.142645] [plugin-manager] [system:info] [Dynamic Capture Example:22964] Accept-Encoding: gzip, deflate, br, zstd
+[2025-05-30 20:44:26.142645] [plugin-manager] [system:info] [Dynamic Capture Example:22964] Accept-Language: zh-TW,zh;q=0.9,en;q=0.8,en-GB;q=0.7,en-US;q=0.6
+[2025-05-30 20:44:26.142645] [plugin-manager] [system:info] [Dynamic Capture Example:22964] Cache-Control: max-age=0
+[2025-05-30 20:44:26.142645] [plugin-manager] [system:info] [Dynamic Capture Example:22964] Sec-Fetch-User: ?1
+[2025-05-30 20:44:26.142645] [plugin-manager] [system:info] [Dynamic Capture Example:22964] Upgrade-Insecure-Requests: 1
+[2025-05-30 20:44:26.142645] [plugin-manager] [system:info] [Dynamic Capture Example:22964] User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Safari/537.36 Edg/136.0.0.0
+[2025-05-30 20:44:26.142645] [plugin-manager] [system:info] [Dynamic Capture Example:22964] Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7
+[2025-05-30 20:44:26.142645] [plugin-manager] [system:info] [Dynamic Capture Example:22964] Priority: u=0, i
+[2025-05-30 20:44:26.143149] [plugin-manager] [system:info] [Dynamic Capture Example:22964] Sec-Ch-Ua-Mobile: ?0
+[2025-05-30 20:44:26.142645] [plugin-manager] [system:info] [Dynamic Capture Example:22964] Sec-Ch-Ua: "Chromium";v="136", "Microsoft Edge";v="136", "Not.A/Brand";v="99"
+[2025-05-30 20:44:26.143165] [plugin-manager] [system:info] [Dynamic Capture Example:22964] Sec-Ch-Ua-Platform: "Windows"
+[2025-05-30 20:44:26.142645] [plugin-manager] [system:info] [Dynamic Capture Example:22964] Sec-Fetch-Site: none
+[2025-05-30 20:44:26.143165] [plugin-manager] [system:info] [Dynamic Capture Example:22964] Sec-Fetch-Mode: navigate
+[2025-05-30 20:44:26.143165] [plugin-manager] [system:info] [Dynamic Capture Example:22964] RemoteAddr: [::1]:54522
+[2025-05-30 20:44:26.143165] [plugin-manager] [system:info] [Dynamic Capture Example:22964] Host: a.localhost
+[2025-05-30 20:44:26.143165] [plugin-manager] [system:info] [Dynamic Capture Example:22964] RequestURI: /foobar/test
+[2025-05-30 20:44:26.143165] [plugin-manager] [system:info] [Dynamic Capture Example:22964] Proto: HTTP/2.0
+[2025-05-30 20:44:26.143165] [plugin-manager] [system:info] [Dynamic Capture Example:22964] ProtoMajor: 2
+[2025-05-30 20:44:26.143165] [plugin-manager] [system:info] [Dynamic Capture Example:22964] ProtoMinor: 0
+
+
+
+
+ Now you know how to develop a plugin in Zoraxy that handles special routings!
+
+
+
+