diff --git a/docs/plugins/build.go b/docs/plugins/build.go index 62bf940..86afdaf 100644 --- a/docs/plugins/build.go +++ b/docs/plugins/build.go @@ -265,7 +265,9 @@ func mdToHTML(md []byte) []byte { // create HTML renderer with extensions htmlFlags := html.CommonFlags | html.HrefTargetBlank - opts := html.RendererOptions{Flags: htmlFlags} + opts := html.RendererOptions{ + Flags: htmlFlags, + } renderer := html.NewRenderer(opts) return markdown.Render(doc, renderer) diff --git a/docs/plugins/cssOptimizer.go b/docs/plugins/cssOptimizer.go index 35cce02..f6147a0 100644 --- a/docs/plugins/cssOptimizer.go +++ b/docs/plugins/cssOptimizer.go @@ -38,46 +38,6 @@ func optimizeCss(htmlContent []byte) ([]byte, error) { //Replace the img with ts-image originalHTMLContent = strings.Replace(originalHTMLContent, orginalParent, "
"+orginalParent+"
", 1) }) - /* - // Replace h* elements - doc.Find("h1").Each(func(i int, s *goquery.Selection) { - originalHeader, err := s.Html() - if err != nil { - fmt.Println("Error getting header HTML:", err) - return - } - - // Patch the bug in the parser that converts " />" to "/>" - originalHeader = strings.ReplaceAll(originalHeader, "/>", " />") - wrappedHeader := fmt.Sprintf("
%s
", originalHeader) - originalHTMLContent = strings.ReplaceAll(originalHTMLContent, s.Text(), wrappedHeader) - }) - */ - doc.Find("h2").Each(func(i int, s *goquery.Selection) { - originalHeader, err := s.Html() - if err != nil { - fmt.Println("Error getting header HTML:", err) - return - } - - // Patch the bug in the parser that converts " />" to "/>" - originalHeader = strings.ReplaceAll(originalHeader, "/>", " />") - wrappedHeader := fmt.Sprintf("
%s
", originalHeader) - originalHTMLContent = strings.ReplaceAll(originalHTMLContent, s.Text(), wrappedHeader) - }) - - doc.Find("h3").Each(func(i int, s *goquery.Selection) { - originalHeader, err := s.Html() - if err != nil { - fmt.Println("Error getting header HTML:", err) - return - } - - // Patch the bug in the parser that converts " />" to "/>" - originalHeader = strings.ReplaceAll(originalHeader, "/>", " />") - wrappedHeader := fmt.Sprintf("
%s
", originalHeader) - originalHTMLContent = strings.ReplaceAll(originalHTMLContent, s.Text(), wrappedHeader) - }) // Add "ts-text" class to each p element doc.Find("p").Each(func(i int, s *goquery.Selection) { @@ -103,7 +63,7 @@ func optimizeCss(htmlContent []byte) ([]byte, error) { } // Replace
with
- originalHTMLContent = strings.ReplaceAll(originalHTMLContent, "
", "
") + originalHTMLContent = strings.ReplaceAll(originalHTMLContent, "
", "
") }) // Add ts-table to all table elements @@ -120,6 +80,43 @@ func optimizeCss(htmlContent []byte) ([]byte, error) { originalHTMLContent = strings.ReplaceAll(originalHTMLContent, originalTable, fmt.Sprintf("%s
", newClass, originalTable)) }) + // Replace -
-

-
- When should you add a core PR or a plugin?
+ +
+

+ When should you add a core PR or a plugin?

In certain situations, implementing a feature as a plugin is more reasonable than directly integrating it into the Zoraxy core:

-
    -
  • - +
    +
    + Core PR - + : If the feature is relevant to most users and enhances Zoraxy’s core functionality, consider submitting a core Pull Request (PR).
    -
    • -
  • - + +
    + Plugin - + : If the feature is targeted at a smaller user base or requires additional dependencies that not all users need, it should be developed as a plugin.
    -
    • -
+ +

The decision depends on the feature’s general relevance and its impact on core stability. Plugins offer flexibility without burdening the core.

diff --git a/docs/plugins/html/1. Introduction/2. Getting Started.html b/docs/plugins/html/1. Introduction/2. Getting Started.html index aeb4921..e0b2111 100644 --- a/docs/plugins/html/1. Introduction/2. Getting Started.html +++ b/docs/plugins/html/1. Introduction/2. Getting Started.html @@ -110,6 +110,9 @@ Configure + + Capture Modes + Getting Started @@ -132,22 +135,20 @@ To start developing plugins, you will need the following installed on your computer

-
    -
  1. +
    +
    The source code of Zoraxy -
    2. -
  2. - Go compiler -
    3. -
  3. - VSCode (recommended, or any editor of your choice) -
    4. -
-
-

-
- Step 1: Start Zoraxy at least once
+
+ Go compiler +
+
+ VSCode (recommended, or any editor of your choice) +
+ +
+

+ Step 1: Start Zoraxy at least once

@@ -167,20 +168,18 @@ sudo ./zoraxy

After the startup process completes, you would see a folder named “plugins” in the working directory of Zoraxy.

-
+

-
- Steps 2: Prepare the development environment for Zoraxy Plugin -
+ Steps 2: Prepare the development environment for Zoraxy Plugin

Next, you will need to think of a name for your plugin. Lets name our new plugin “Lapwing”.

- + Notes: Plugin name described in Introspect (will discuss this in later sessions) can contains space, but the folder and compiled binary filename must not contains space and special characters for platform compatibilities reasons. - +

@@ -189,96 +188,88 @@ sudo ./zoraxy

-
- 2.1 Create Plugin Folder -
+ 2.1 Create Plugin Folder

Create a folder with your plugin name in the - + plugins - + folder. After creating the folder, you would have something like - + plugins/Lapwing/ - + .

-
- 2.2 Locate and copy Zoraxy Plugin library -
+ 2.2 Locate and copy Zoraxy Plugin library

Locate the Zoraxy plugin library from the Zoraxy source code. You can find the - + zoraxy_plugin - + Go module under - + src/mod/plugins/zoraxy_plugin - + .

Copy the - + zoraxy_plugin - + folder from the Zoraxy source code mod folder into the your plugin’s mod folder. Let assume you use the same mod folder name as Zoraxy as - + mod - + , then your copied library path should be - + plugins/Lapwing/mod/zoraxy_plugin - + .

-
- 2.3 Prepare Go Project structure -
+ 2.3 Prepare Go Project structure

Create the - + main.go - + file for your plugin. In the example above, it would be located at - + plugins/Lapwing/main.go - + .

Use - + go mod init yourdomain.com/foo/plugin_name - + to initiate your plugin. By default the - + go.mod - + file will be automatically generated by the go compiler. Assuming you are developing Lapwing with its source located on Github, this command would be - + go mod init github.com/your_user_name/Lapwing - + .

-
+

-
- Steps 3: Open plugin folder in IDE -
+ Steps 3: Open plugin folder in IDE

diff --git a/docs/plugins/html/2. Architecture/1. Plugin Architecture.html b/docs/plugins/html/2. Architecture/1. Plugin Architecture.html index 59d4c2b..baa6b4e 100644 --- a/docs/plugins/html/2. Architecture/1. Plugin Architecture.html +++ b/docs/plugins/html/2. Architecture/1. Plugin Architecture.html @@ -110,6 +110,9 @@ Configure + + Capture Modes + Getting Started @@ -132,17 +135,17 @@ The Zoraxy Plugin uses a 3 steps approach to get information from plugin, setup the plugin and forward request to plugin. The name of the steps are partially referred from dbus designs as followings.

-
    -
  1. +
    +
    Introspect -
    2. -
  2. + +
    Configure -
    3. -
  3. + +
    Forwarding -
    4. -
+ +

The overall flow looks like this. diff --git a/docs/plugins/html/2. Architecture/2. Introspect.html b/docs/plugins/html/2. Architecture/2. Introspect.html index 62d1b0c..3e2154d 100644 --- a/docs/plugins/html/2. Architecture/2. Introspect.html +++ b/docs/plugins/html/2. Architecture/2. Introspect.html @@ -110,6 +110,9 @@ Configure + + Capture Modes + Getting Started @@ -134,22 +137,22 @@

- + This is a pre-defined structure where the plugin must provide to Zoraxy - + when the plugin is being started with the - + -introspect - + flag.

The introspect structure is defined under the - + zoraxy_plugin - + library, where both Zoraxy and plugin should use. As of writing, the structure of introspect is like this.

@@ -200,17 +203,15 @@ SubscriptionsEvents map[string]string `json:"subscriptions_events"` //Subscriptions events of your plugin, see Zoraxy documentation for more details } -

-
- Introspect Triggering -
+

+ Introspect Manual Triggering

To manually test if the introspect return is correct, you can try using the - + -introspect - + flag on any Zoraxy plugin. You should be able to see an output like so.

diff --git a/docs/plugins/html/2. Architecture/3. Configure.html b/docs/plugins/html/2. Architecture/3. Configure.html index fb1f884..6b62dae 100644 --- a/docs/plugins/html/2. Architecture/3. Configure.html +++ b/docs/plugins/html/2. Architecture/3. Configure.html @@ -110,6 +110,9 @@ Configure + + Capture Modes + Getting Started @@ -130,22 +133,22 @@

Configure or Configure Spec is the - + exec - + call where Zoraxy start the plugin. The configure spec JSON structure is defined in - + zoraxy_plugin - + library.

As the time of writing, the - + ConfigureSpec - + only contains information on some basic info.

@@ -159,22 +162,22 @@

The - + ConfigureSpec - + struct will be parsed to JSON and pass to your plugin via the - + -configure=(json payload here) - + .

In your plugin, you can use the - + zoraxy_plugin - + library to parse it or parse it manually (if you are developing a plugin with other languages).

diff --git a/docs/plugins/html/2. Architecture/4. Capture Modes.html b/docs/plugins/html/2. Architecture/4. Capture Modes.html new file mode 100644 index 0000000..800155e --- /dev/null +++ b/docs/plugins/html/2. Architecture/4. Capture Modes.html @@ -0,0 +1,331 @@ + + + + + + + + Capture Modes | Zoraxy Documentation + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+ + + + + Documents + + + Examples + +
+
+
+
+
+
+
+
+
+
+ + Introduction + + +
+ + What is Zoraxy Plugin + + + Getting Started + +
+ + Architecture + + +
+ + Plugin Architecture + + + Introspect + + + Configure + + + Capture Modes + +
+ + Getting Started + + + + index + +
+
+
+
+
+
+

+ Capture Modes +

+

+

+ As you can see in the Introspect section, there are two types of capture mode in Zoraxy plugin API. +

+

+
+
+ Static Capture Mode +
+
+ Dynamic Capture Mode +
+
+

+ + Notes: When this document mention the term “endpoint”, it means a particular sub-path on the plugin side. For example + + /capture + + or + + /sniff + + . In actual implementation, this can be a + + http.HandleFunc + + or + + http.Handle + + depends on the plugin implementation. + +

+
+

+ Static Capture Mode +

+

+

+ Static Capture Mode register a static path to Zoraxy, when the plugin is enabled on a certain HTTP proxy rule, all request that matches the static capture registered paths are forwarded to the plugin without asking first. The overall process is shown in the diagram below. +

+

+

+

+ static_capture +
+

+

+

+ The main benefit of static capture mode is that the capture paths are stored in radix tree. That means it takes O(logn) time to resolve the path and forward the request. Hence, + + this mode is generally faster + + if your plugin always listens to a few certain paths for extended functionalities. +

+

+
+

+ Dynamic Capture Mode +

+

+

+ Dynamic Capture Mode register two endpoints to Zoraxy. +

+

+
+
+ DynamicCaptureSniff - The sniffing endpoint where Zoraxy will first ask if the plugin want to handle this request +
+
+ DynamicCaptureIngress - The handling endpoint, where if the plugin reply the sniffing with “YES”, Zoraxy forward the incoming request to this plugin at this defined endpoint. +
+
+

+

+ The whole process will takes a few request exchange between plugin and Zoraxy core. Since both of them are communicating via the loopback interface, speed should not be too big of a concern here. +

+

+

+

+ The request handling flow is shown in the diagram below. +

+

+

+

+ dynamic_capture +
+

+

+

+ Once Zoraxy receive a request from a client that matches one of the HTTP Proxy Rule, Zoraxy will forward the request header to all the plugins that matches the following criteria +

+

+
+
+ The plugin is assigned to a tag that is currently attached to the given HTTP Proxy that the request is coming through +
+
+ The plugin is enabled and running +
+
+ The plugin has registered its dynamic capture sniffing endpoint in Introspect +
+
+

+

+ Then the plugin + + /sniff + + endpoint will receive some basic header information about the request, and response with + + SniffResultAccpet + + or + + SniffResultSkip + + to accept or reject handling such request. The response are defined in + + zoraxy_plugin + + as a public type where you can access with + + zoraxy_plugin.SniffresultAccept + + and + + zoraxy_plugin.SniffResultSkip + + respectively. +

+

+

+

+ Note that this shall only be used if static capture mode cannot satisfy your needs in implementation the feature you want, as + + dynamic capture is way slower than static capture mode + + . +

+

+
+

+ Mixing Capture Modes +

+

+

+ It is possible for you to mix both Static and Capture modes if that is what you want. A few thing you need to know about mixing both mode in single plugin +

+

+
+
+ Static capture mode has higher priority than dynamic capture mode across all plugins. That means if you have a request that matches Plugin A’s static capture path and Plugin B’s dynamic capture, the request will be first handled by Plugin A +
+
+ The same plugin can register both static and dynamic capture modes. Similar to item (1), if the request has already captured by your static capture path, Zoraxy will not proceed and forward the request header to your dynamic sniffing endpoint. +
+
+ In case there is a collision in static capture paths between two plugins, the longest one will have priority. For example, if Plugin A registered + + /foo + + and Plugin B registered + + /foo/bar + + , when a request to + + /foo/bar/teacat + + enter Zoraxy, Plugin B is used for handling such request. +
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Zoraxy © tobychui + + 2025 + +
+
+
+ + + \ No newline at end of file diff --git a/docs/plugins/html/2. Architecture/img/4. Capture Modes/dynamic_capture.png b/docs/plugins/html/2. Architecture/img/4. Capture Modes/dynamic_capture.png new file mode 100644 index 0000000..0083370 Binary files /dev/null and b/docs/plugins/html/2. Architecture/img/4. Capture Modes/dynamic_capture.png differ diff --git a/docs/plugins/html/2. Architecture/img/4. Capture Modes/static_capture.png b/docs/plugins/html/2. Architecture/img/4. Capture Modes/static_capture.png new file mode 100644 index 0000000..0c51c52 Binary files /dev/null and b/docs/plugins/html/2. Architecture/img/4. Capture Modes/static_capture.png differ diff --git a/docs/plugins/html/index.html b/docs/plugins/html/index.html index 772c84b..634a058 100644 --- a/docs/plugins/html/index.html +++ b/docs/plugins/html/index.html @@ -110,6 +110,9 @@ Configure + + Capture Modes + Getting Started @@ -133,14 +136,10 @@ Click on a topic in the side menu to begin navigating through the available resources and guides for developing and managing plugins.

-
- FAQ -
+ FAQ

-
- What skills do I need for developing a plugin? -
+ What skills do I need for developing a plugin?

@@ -148,9 +147,7 @@

-
- Will a plugin crash the whole Zoraxy? -
+ Will a plugin crash the whole Zoraxy?

@@ -158,9 +155,7 @@

-
- Can I sell my plugin? -
+ Can I sell my plugin?

@@ -168,9 +163,7 @@

-
- How can I add my plugin to the official plugin store? -
+ How can I add my plugin to the official plugin store?

diff --git a/docs/plugins/index.json b/docs/plugins/index.json index b4d20c9..ca463b9 100644 --- a/docs/plugins/index.json +++ b/docs/plugins/index.json @@ -39,6 +39,11 @@ "filename": "2. Architecture/3. Configure.md", "title": "Configure", "type": "file" + }, + { + "filename": "2. Architecture/4. Capture Modes.md", + "title": "Capture Modes", + "type": "file" } ] },