From eec6cec0dbff9c57d0135e0988c6517cf9daf786 Mon Sep 17 00:00:00 2001 From: Toby Chui Date: Sat, 31 May 2025 14:23:11 +0800 Subject: [PATCH] Added api doc - Added zoraxy_plugin module api doc generating script - Added link to example source folder - Fixed a few minor typo --- docs/plugins/dev.sh | 8 +- .../3. Static Capture Example.md | 2 - docs/plugins/docs/zoraxy_plugin API.md | 257 ++++++++++ docs/plugins/gen_zoraxy_plugin_doc.sh | 23 + .../1. What is Zoraxy Plugin.html | 6 +- .../1. Introduction/2. Getting Started.html | 6 +- .../1. Introduction/3. Installing Plugin.html | 6 +- .../1. Introduction/4. Enable Plugins.html | 6 +- .../5. Viewing Plugin Info.html | 6 +- .../1. Plugin Architecture.html | 6 +- .../html/2. Architecture/2. Introspect.html | 6 +- .../html/2. Architecture/3. Configure.html | 6 +- .../2. Architecture/4. Capture Modes.html | 6 +- .../html/2. Architecture/5. Plugin UI.html | 6 +- .../2. Architecture/6. Compile a Plugin.html | 6 +- .../3. Basic Examples/1. Hello World.html | 6 +- .../3. Basic Examples/2. RESTful Example.html | 6 +- .../3. Static Capture Example.html | 9 +- .../4. Dynamic Capture Example.html | 6 +- docs/plugins/html/index.html | 6 +- docs/plugins/html/zoraxy_plugin API.html | 448 ++++++++++++++++++ docs/plugins/index.json | 5 + docs/plugins/template/documents.html | 4 +- 23 files changed, 822 insertions(+), 24 deletions(-) create mode 100644 docs/plugins/docs/zoraxy_plugin API.md create mode 100644 docs/plugins/gen_zoraxy_plugin_doc.sh create mode 100644 docs/plugins/html/zoraxy_plugin API.html diff --git a/docs/plugins/dev.sh b/docs/plugins/dev.sh index 8610323..dbe63f1 100644 --- a/docs/plugins/dev.sh +++ b/docs/plugins/dev.sh @@ -3,4 +3,10 @@ go build # Run the Go program with the specified arguments ./docs.exe -m=build -./docs.exe \ No newline at end of file +echo "Running docs in development mode..." +./docs.exe + +# After the docs web server mode terminate, rebuild it with root = plugins/html/ +./docs.exe -m=build -root=plugins/html/ + +# The doc should always be ready to push to release branch diff --git a/docs/plugins/docs/3. Basic Examples/3. Static Capture Example.md b/docs/plugins/docs/3. Basic Examples/3. Static Capture Example.md index c7549a6..46c4d45 100644 --- a/docs/plugins/docs/3. Basic Examples/3. Static Capture Example.md +++ b/docs/plugins/docs/3. Basic Examples/3. Static Capture Example.md @@ -7,8 +7,6 @@ This example demonstrates how to use static capture in Zoraxy plugins. Static ca **Notes: This example assumes you have already read Hello World example.** -Let's dive in! - --- ## 1. Create the plugin folder structure diff --git a/docs/plugins/docs/zoraxy_plugin API.md b/docs/plugins/docs/zoraxy_plugin API.md new file mode 100644 index 0000000..9206f75 --- /dev/null +++ b/docs/plugins/docs/zoraxy_plugin API.md @@ -0,0 +1,257 @@ +# Zoraxy Plugin APIs +This API documentation is auto-generated from the Zoraxy plugin source code. + + +

+package zoraxy_plugin // import "{{your_module_package_name_in_go.mod}}/mod/plugins/zoraxy_plugin"
+
+
+FUNCTIONS
+
+func ServeIntroSpect(pluginSpect *IntroSpect)
+    ServeIntroSpect Function
+
+    This function will check if the plugin is initialized with -introspect flag,
+    if so, it will print the intro spect and exit
+
+    Place this function at the beginning of your plugin main function
+
+
+TYPES
+
+type ConfigureSpec struct {
+	Port         int                  `json:"port"`          //Port to listen
+	RuntimeConst RuntimeConstantValue `json:"runtime_const"` //Runtime constant values
+
+}
+    ConfigureSpec Payload
+
+    Zoraxy will start your plugin with -configure flag, the plugin shell read
+    this payload as JSON and configure itself by the supplied values like
+    starting a web server at given port that listens to 127.0.0.1:port
+
+func RecvConfigureSpec() (*ConfigureSpec, error)
+    RecvExecuteConfigureSpec Function
+
+    This function will read the configure spec from Zoraxy and return the
+    ConfigureSpec object
+
+    Place this function after ServeIntroSpect function in your plugin main
+    function
+
+func ServeAndRecvSpec(pluginSpect *IntroSpect) (*ConfigureSpec, error)
+    ServeAndRecvSpec Function
+
+    This function will serve the intro spect and return the configure spec See
+    the ServeIntroSpect and RecvConfigureSpec for more details
+
+type ControlStatusCode int
+
+const (
+	ControlStatusCode_CAPTURED  ControlStatusCode = 280 //Traffic captured by plugin, ask Zoraxy not to process the traffic
+	ControlStatusCode_UNHANDLED ControlStatusCode = 284 //Traffic not handled by plugin, ask Zoraxy to process the traffic
+	ControlStatusCode_ERROR     ControlStatusCode = 580 //Error occurred while processing the traffic, ask Zoraxy to process the traffic and log the error
+)
+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"`
+
+	// Has unexported fields.
+}
+        Sniffing and forwarding
+
+        The following functions are here to help with
+        sniffing and forwarding requests to the dynamic
+        router.
+
+    A custom request object to be used in the dynamic sniffing
+
+func DecodeForwardRequestPayload(jsonBytes []byte) (DynamicSniffForwardRequest, error)
+    DecodeForwardRequestPayload decodes JSON bytes into a
+    DynamicSniffForwardRequest object
+
+func EncodeForwardRequestPayload(r *http.Request) DynamicSniffForwardRequest
+    GetForwardRequestPayload returns a DynamicSniffForwardRequest object from an
+    http.Request object
+
+func (dsfr *DynamicSniffForwardRequest) GetRequest() *http.Request
+    GetRequest returns the original http.Request object, for debugging purposes
+
+func (dsfr *DynamicSniffForwardRequest) GetRequestUUID() string
+    GetRequestUUID returns the request UUID if this UUID is empty string,
+    that might indicate the request is not coming from the dynamic router
+
+type IntroSpect struct {
+	//  Plugin metadata
+	ID            string     `json:"id"`             //Unique ID of your plugin, recommended using your own domain in reverse like com.yourdomain.pluginname
+	Name          string     `json:"name"`           //Name of your plugin
+	Author        string     `json:"author"`         //Author name of your plugin
+	AuthorContact string     `json:"author_contact"` //Author contact of your plugin, like email
+	Description   string     `json:"description"`    //Description of your plugin
+	URL           string     `json:"url"`            //URL of your plugin
+	Type          PluginType `json:"type"`           //Type of your plugin, Router(0) or Utilities(1)
+	VersionMajor  int        `json:"version_major"`  //Major version of your plugin
+	VersionMinor  int        `json:"version_minor"`  //Minor version of your plugin
+	VersionPatch  int        `json:"version_patch"`  //Patch version of your plugin
+
+	//		Static Capture Settings
+	//
+	//		Once plugin is enabled these rules always applies to the enabled HTTP Proxy rule
+	//		This is faster than dynamic capture, but less flexible
+
+	StaticCapturePaths   []StaticCaptureRule `json:"static_capture_paths"`   //Static capture paths of your plugin, see Zoraxy documentation for more details
+	StaticCaptureIngress string              `json:"static_capture_ingress"` //Static capture ingress path of your plugin (e.g. /s_handler)
+
+	//		Dynamic Capture Settings
+	//
+	//		Once plugin is enabled, these rules will be captured and forward to plugin sniff
+	//		if the plugin sniff returns 280, the traffic will be captured
+	//		otherwise, the traffic will be forwarded to the next plugin
+	//		This is slower than static capture, but more flexible
+
+	DynamicCaptureSniff   string `json:"dynamic_capture_sniff"`   //Dynamic capture sniff path of your plugin (e.g. /d_sniff)
+	DynamicCaptureIngress string `json:"dynamic_capture_ingress"` //Dynamic capture ingress path of your plugin (e.g. /d_handler)
+
+	//  UI Path for your plugin
+	UIPath string `json:"ui_path"` //UI path of your plugin (e.g. /ui), will proxy the whole subpath tree to Zoraxy Web UI as plugin UI
+
+	//  Subscriptions Settings
+	SubscriptionPath    string            `json:"subscription_path"`    //Subscription event path of your plugin (e.g. /notifyme), a POST request with SubscriptionEvent as body will be sent to this path when the event is triggered
+	SubscriptionsEvents map[string]string `json:"subscriptions_events"` //Subscriptions events of your plugin, see Zoraxy documentation for more details
+}
+    IntroSpect Payload
+
+    When the plugin is initialized with -introspect flag, the plugin shell
+    return this payload as JSON and exit
+
+type PathRouter struct {
+	// Has unexported fields.
+}
+
+func NewPathRouter() *PathRouter
+    NewPathRouter creates a new PathRouter
+
+func (p *PathRouter) PrintRequestDebugMessage(r *http.Request)
+
+func (p *PathRouter) RegisterDynamicCaptureHandle(capture_ingress string, mux *http.ServeMux, handlefunc func(http.ResponseWriter, *http.Request))
+    RegisterDynamicCaptureHandle register the dynamic capture ingress path with
+    a handler
+
+func (p *PathRouter) RegisterDynamicSniffHandler(sniff_ingress string, mux *http.ServeMux, handler SniffHandler)
+    RegisterDynamicSniffHandler registers a dynamic sniff handler for a path
+    You can decide to accept or skip the request based on the request header and
+    paths
+
+func (p *PathRouter) RegisterPathHandler(path string, handler http.Handler)
+    RegisterPathHandler registers a handler for a path
+
+func (p *PathRouter) RegisterStaticCaptureHandle(capture_ingress string, mux *http.ServeMux)
+    StartStaticCapture starts the static capture ingress
+
+func (p *PathRouter) RemovePathHandler(path string)
+    RemovePathHandler removes a handler for a path
+
+func (p *PathRouter) SetDebugPrintMode(enable bool)
+    SetDebugPrintMode sets the debug print mode
+
+func (p *PathRouter) SetDefaultHandler(handler http.Handler)
+    SetDefaultHandler sets the default handler for the router This handler will
+    be called if no path handler is found
+
+type PluginType int
+
+const (
+	PluginType_Router    PluginType = 0 //Router Plugin, used for handling / routing / forwarding traffic
+	PluginType_Utilities PluginType = 1 //Utilities Plugin, used for utilities like Zerotier or Static Web Server that do not require interception with the dpcore
+)
+type PluginUiDebugRouter struct {
+	PluginID      string //The ID of the plugin
+	TargetDir     string //The directory where the UI files are stored
+	HandlerPrefix string //The prefix of the handler used to route this router, e.g. /ui
+	EnableDebug   bool   //Enable debug mode
+	// Has unexported fields.
+}
+
+func NewPluginFileSystemUIRouter(pluginID string, targetDir string, handlerPrefix string) *PluginUiDebugRouter
+    NewPluginFileSystemUIRouter creates a new PluginUiRouter with file system
+    The targetDir is the directory where the UI files are stored (e.g. ./www)
+    The handlerPrefix is the prefix of the handler used to route this router
+    The handlerPrefix should start with a slash (e.g. /ui) that matches the
+    http.Handle path All prefix should not end with a slash
+
+func (p *PluginUiDebugRouter) AttachHandlerToMux(mux *http.ServeMux)
+    Attach the file system UI handler to the target http.ServeMux
+
+func (p *PluginUiDebugRouter) Handler() http.Handler
+    GetHttpHandler returns the http.Handler for the PluginUiRouter
+
+func (p *PluginUiDebugRouter) RegisterTerminateHandler(termFunc func(), mux *http.ServeMux)
+    RegisterTerminateHandler registers the terminate handler for the
+    PluginUiRouter The terminate handler will be called when the plugin is
+    terminated from Zoraxy plugin manager if mux is nil, the handler will be
+    registered to http.DefaultServeMux
+
+type PluginUiRouter struct {
+	PluginID       string    //The ID of the plugin
+	TargetFs       *embed.FS //The embed.FS where the UI files are stored
+	TargetFsPrefix string    //The prefix of the embed.FS where the UI files are stored, e.g. /web
+	HandlerPrefix  string    //The prefix of the handler used to route this router, e.g. /ui
+	EnableDebug    bool      //Enable debug mode
+	// Has unexported fields.
+}
+
+func NewPluginEmbedUIRouter(pluginID string, targetFs *embed.FS, targetFsPrefix string, handlerPrefix string) *PluginUiRouter
+    NewPluginEmbedUIRouter creates a new PluginUiRouter with embed.FS The
+    targetFsPrefix is the prefix of the embed.FS where the UI files are stored
+    The targetFsPrefix should be relative to the root of the embed.FS The
+    targetFsPrefix should start with a slash (e.g. /web) that corresponds to the
+    root folder of the embed.FS The handlerPrefix is the prefix of the handler
+    used to route this router The handlerPrefix should start with a slash (e.g.
+    /ui) that matches the http.Handle path All prefix should not end with a
+    slash
+
+func (p *PluginUiRouter) AttachHandlerToMux(mux *http.ServeMux)
+    Attach the embed UI handler to the target http.ServeMux
+
+func (p *PluginUiRouter) Handler() http.Handler
+    GetHttpHandler returns the http.Handler for the PluginUiRouter
+
+func (p *PluginUiRouter) RegisterTerminateHandler(termFunc func(), mux *http.ServeMux)
+    RegisterTerminateHandler registers the terminate handler for the
+    PluginUiRouter The terminate handler will be called when the plugin is
+    terminated from Zoraxy plugin manager if mux is nil, the handler will be
+    registered to http.DefaultServeMux
+
+type RuntimeConstantValue struct {
+	ZoraxyVersion    string `json:"zoraxy_version"`
+	ZoraxyUUID       string `json:"zoraxy_uuid"`
+	DevelopmentBuild bool   `json:"development_build"` //Whether the Zoraxy is a development build or not
+}
+
+type SniffHandler func(*DynamicSniffForwardRequest) SniffResult
+
+type SniffResult int
+
+const (
+	SniffResultAccpet SniffResult = iota // Forward the request to this plugin dynamic capture ingress
+	SniffResultSkip                      // Skip this plugin and let the next plugin handle the request
+)
+type StaticCaptureRule struct {
+	CapturePath string `json:"capture_path"`
+}
+
+type SubscriptionEvent struct {
+	EventName   string `json:"event_name"`
+	EventSource string `json:"event_source"`
+	Payload     string `json:"payload"` //Payload of the event, can be empty
+}
+
+
diff --git a/docs/plugins/gen_zoraxy_plugin_doc.sh b/docs/plugins/gen_zoraxy_plugin_doc.sh new file mode 100644 index 0000000..9e74444 --- /dev/null +++ b/docs/plugins/gen_zoraxy_plugin_doc.sh @@ -0,0 +1,23 @@ +#/bin/bash + +# Cd into zoraxy plugin directory +cd ../../src/mod/plugins/zoraxy_plugin/ + + +# Add header to the documentation +echo "# Zoraxy Plugin APIs" > docs.md +echo "This API documentation is auto-generated from the Zoraxy plugin source code." >> docs.md +echo "" >> docs.md +echo "" >> docs.md +echo "
" >> docs.md
+go doc -all >> docs.md
+echo "
" >> docs.md + +# Replace // import "imuslab.com/zoraxy/mod/plugins/zoraxy_plugin" with +# // import "{{your_module_package_name_in_go.mod}}/mod/plugins/zoraxy_plugin" +sed -i 's|// import "imuslab.com/zoraxy/mod/plugins/zoraxy_plugin"|// import "{{your_module_package_name_in_go.mod}}/mod/plugins/zoraxy_plugin"|g' docs.md + +# Move the generated docs to the plugins/html directory +mv docs.md "../../../../docs/plugins/docs/zoraxy_plugin API.md" + +echo "Done generating Zoraxy plugin documentation." diff --git a/docs/plugins/html/1. Introduction/1. What is Zoraxy Plugin.html b/docs/plugins/html/1. Introduction/1. What is Zoraxy Plugin.html index 3180721..a59b780 100644 --- a/docs/plugins/html/1. Introduction/1. What is Zoraxy Plugin.html +++ b/docs/plugins/html/1. Introduction/1. What is Zoraxy Plugin.html @@ -69,8 +69,9 @@ Documents - + Examples + @@ -148,6 +149,9 @@ index + + zoraxy_plugin API + diff --git a/docs/plugins/html/1. Introduction/2. Getting Started.html b/docs/plugins/html/1. Introduction/2. Getting Started.html index 85ebcca..55832a9 100644 --- a/docs/plugins/html/1. Introduction/2. Getting Started.html +++ b/docs/plugins/html/1. Introduction/2. Getting Started.html @@ -69,8 +69,9 @@ Documents - + Examples + @@ -148,6 +149,9 @@ index + + zoraxy_plugin API + diff --git a/docs/plugins/html/1. Introduction/3. Installing Plugin.html b/docs/plugins/html/1. Introduction/3. Installing Plugin.html index 7ded495..76228c7 100644 --- a/docs/plugins/html/1. Introduction/3. Installing Plugin.html +++ b/docs/plugins/html/1. Introduction/3. Installing Plugin.html @@ -69,8 +69,9 @@ Documents - + Examples + @@ -148,6 +149,9 @@ index + + zoraxy_plugin API + diff --git a/docs/plugins/html/1. Introduction/4. Enable Plugins.html b/docs/plugins/html/1. Introduction/4. Enable Plugins.html index 8ba0e23..67aad94 100644 --- a/docs/plugins/html/1. Introduction/4. Enable Plugins.html +++ b/docs/plugins/html/1. Introduction/4. Enable Plugins.html @@ -69,8 +69,9 @@ Documents - + Examples + @@ -148,6 +149,9 @@ index + + zoraxy_plugin API + diff --git a/docs/plugins/html/1. Introduction/5. Viewing Plugin Info.html b/docs/plugins/html/1. Introduction/5. Viewing Plugin Info.html index e5b558b..84cc2f1 100644 --- a/docs/plugins/html/1. Introduction/5. Viewing Plugin Info.html +++ b/docs/plugins/html/1. Introduction/5. Viewing Plugin Info.html @@ -69,8 +69,9 @@ Documents - + Examples + @@ -148,6 +149,9 @@ index + + zoraxy_plugin API + diff --git a/docs/plugins/html/2. Architecture/1. Plugin Architecture.html b/docs/plugins/html/2. Architecture/1. Plugin Architecture.html index abcd45d..ff12afd 100644 --- a/docs/plugins/html/2. Architecture/1. Plugin Architecture.html +++ b/docs/plugins/html/2. Architecture/1. Plugin Architecture.html @@ -69,8 +69,9 @@ Documents - + Examples + @@ -148,6 +149,9 @@ index + + zoraxy_plugin API + diff --git a/docs/plugins/html/2. Architecture/2. Introspect.html b/docs/plugins/html/2. Architecture/2. Introspect.html index 8fc32e7..513ca9f 100644 --- a/docs/plugins/html/2. Architecture/2. Introspect.html +++ b/docs/plugins/html/2. Architecture/2. Introspect.html @@ -69,8 +69,9 @@ Documents - + Examples + @@ -148,6 +149,9 @@ index + + zoraxy_plugin API + diff --git a/docs/plugins/html/2. Architecture/3. Configure.html b/docs/plugins/html/2. Architecture/3. Configure.html index a8c08ae..d069dec 100644 --- a/docs/plugins/html/2. Architecture/3. Configure.html +++ b/docs/plugins/html/2. Architecture/3. Configure.html @@ -69,8 +69,9 @@ Documents - + Examples + @@ -148,6 +149,9 @@ index + + zoraxy_plugin API + diff --git a/docs/plugins/html/2. Architecture/4. Capture Modes.html b/docs/plugins/html/2. Architecture/4. Capture Modes.html index 6ad08e0..3a25716 100644 --- a/docs/plugins/html/2. Architecture/4. Capture Modes.html +++ b/docs/plugins/html/2. Architecture/4. Capture Modes.html @@ -69,8 +69,9 @@ Documents - + Examples + @@ -148,6 +149,9 @@ index + + zoraxy_plugin API + diff --git a/docs/plugins/html/2. Architecture/5. Plugin UI.html b/docs/plugins/html/2. Architecture/5. Plugin UI.html index 02650ae..a7b45c6 100644 --- a/docs/plugins/html/2. Architecture/5. Plugin UI.html +++ b/docs/plugins/html/2. Architecture/5. Plugin UI.html @@ -69,8 +69,9 @@ Documents - + Examples + @@ -148,6 +149,9 @@ index + + zoraxy_plugin API + diff --git a/docs/plugins/html/2. Architecture/6. Compile a Plugin.html b/docs/plugins/html/2. Architecture/6. Compile a Plugin.html index fb52d9c..677947d 100644 --- a/docs/plugins/html/2. Architecture/6. Compile a Plugin.html +++ b/docs/plugins/html/2. Architecture/6. Compile a Plugin.html @@ -69,8 +69,9 @@ Documents - + Examples + @@ -148,6 +149,9 @@ index + + zoraxy_plugin API + diff --git a/docs/plugins/html/3. Basic Examples/1. Hello World.html b/docs/plugins/html/3. Basic Examples/1. Hello World.html index 32527a1..8ef0d90 100644 --- a/docs/plugins/html/3. Basic Examples/1. Hello World.html +++ b/docs/plugins/html/3. Basic Examples/1. Hello World.html @@ -69,8 +69,9 @@ Documents - + Examples + @@ -148,6 +149,9 @@ index + + zoraxy_plugin API + diff --git a/docs/plugins/html/3. Basic Examples/2. RESTful Example.html b/docs/plugins/html/3. Basic Examples/2. RESTful Example.html index 9e9d97f..3ee805b 100644 --- a/docs/plugins/html/3. Basic Examples/2. RESTful Example.html +++ b/docs/plugins/html/3. Basic Examples/2. RESTful Example.html @@ -69,8 +69,9 @@ Documents - + Examples + @@ -148,6 +149,9 @@ index + + zoraxy_plugin API + diff --git a/docs/plugins/html/3. Basic Examples/3. Static Capture Example.html b/docs/plugins/html/3. Basic Examples/3. Static Capture Example.html index be8291d..492bca4 100644 --- a/docs/plugins/html/3. Basic Examples/3. Static Capture Example.html +++ b/docs/plugins/html/3. Basic Examples/3. Static Capture Example.html @@ -69,8 +69,9 @@ Documents - + Examples + @@ -148,6 +149,9 @@ index + + zoraxy_plugin API + @@ -175,9 +179,6 @@

-

- Let’s dive in! -

1. Create the plugin folder structure diff --git a/docs/plugins/html/3. Basic Examples/4. Dynamic Capture Example.html b/docs/plugins/html/3. Basic Examples/4. Dynamic Capture Example.html index 366627d..35c786e 100644 --- a/docs/plugins/html/3. Basic Examples/4. Dynamic Capture Example.html +++ b/docs/plugins/html/3. Basic Examples/4. Dynamic Capture Example.html @@ -69,8 +69,9 @@ Documents - + Examples + @@ -148,6 +149,9 @@ index + + zoraxy_plugin API + diff --git a/docs/plugins/html/index.html b/docs/plugins/html/index.html index ba6f220..991edb6 100644 --- a/docs/plugins/html/index.html +++ b/docs/plugins/html/index.html @@ -69,8 +69,9 @@ Documents - + Examples + @@ -148,6 +149,9 @@ index + + zoraxy_plugin API + diff --git a/docs/plugins/html/zoraxy_plugin API.html b/docs/plugins/html/zoraxy_plugin API.html new file mode 100644 index 0000000..cad0901 --- /dev/null +++ b/docs/plugins/html/zoraxy_plugin API.html @@ -0,0 +1,448 @@ + + + + + + + + zoraxy_plugin API | Zoraxy Documentation + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ +
+
+ + + + + Documents + + + Examples + + +
+
+
+
+
+
+
+
+
+
+ + Introduction + + +
+ + What is Zoraxy Plugin + + + Getting Started + + + Installing Plugin + + + Enable Plugins + + + Viewing Plugin Info + +
+ + Architecture + + +
+ + Plugin Architecture + + + Introspect + + + Configure + + + Capture Modes + + + Plugin UI + + + Compile a Plugin + +
+ + Basic Examples + + +
+ + Hello World + + + RESTful Example + + + Static Capture Example + + + Dynamic Capture Example + +
+ + index + + + zoraxy_plugin API + +
+
+
+
+
+
+

+ Zoraxy Plugin APIs +

+

+

+ This API documentation is auto-generated from the Zoraxy plugin source code. +

+

+ 

+package zoraxy_plugin // import "{{your_module_package_name_in_go.mod}}/mod/plugins/zoraxy_plugin"
+
+
+FUNCTIONS
+
+func ServeIntroSpect(pluginSpect *IntroSpect)
+    ServeIntroSpect Function
+
+    This function will check if the plugin is initialized with -introspect flag,
+    if so, it will print the intro spect and exit
+
+    Place this function at the beginning of your plugin main function
+
+
+TYPES
+
+type ConfigureSpec struct {
+	Port         int                  `json:"port"`          //Port to listen
+	RuntimeConst RuntimeConstantValue `json:"runtime_const"` //Runtime constant values
+
+}
+    ConfigureSpec Payload
+
+    Zoraxy will start your plugin with -configure flag, the plugin shell read
+    this payload as JSON and configure itself by the supplied values like
+    starting a web server at given port that listens to 127.0.0.1:port
+
+func RecvConfigureSpec() (*ConfigureSpec, error)
+    RecvExecuteConfigureSpec Function
+
+    This function will read the configure spec from Zoraxy and return the
+    ConfigureSpec object
+
+    Place this function after ServeIntroSpect function in your plugin main
+    function
+
+func ServeAndRecvSpec(pluginSpect *IntroSpect) (*ConfigureSpec, error)
+    ServeAndRecvSpec Function
+
+    This function will serve the intro spect and return the configure spec See
+    the ServeIntroSpect and RecvConfigureSpec for more details
+
+type ControlStatusCode int
+
+const (
+	ControlStatusCode_CAPTURED  ControlStatusCode = 280 //Traffic captured by plugin, ask Zoraxy not to process the traffic
+	ControlStatusCode_UNHANDLED ControlStatusCode = 284 //Traffic not handled by plugin, ask Zoraxy to process the traffic
+	ControlStatusCode_ERROR     ControlStatusCode = 580 //Error occurred while processing the traffic, ask Zoraxy to process the traffic and log the error
+)
+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"`
+
+	// Has unexported fields.
+}
+        Sniffing and forwarding
+
+        The following functions are here to help with
+        sniffing and forwarding requests to the dynamic
+        router.
+
+    A custom request object to be used in the dynamic sniffing
+
+func DecodeForwardRequestPayload(jsonBytes []byte) (DynamicSniffForwardRequest, error)
+    DecodeForwardRequestPayload decodes JSON bytes into a
+    DynamicSniffForwardRequest object
+
+func EncodeForwardRequestPayload(r *http.Request) DynamicSniffForwardRequest
+    GetForwardRequestPayload returns a DynamicSniffForwardRequest object from an
+    http.Request object
+
+func (dsfr *DynamicSniffForwardRequest) GetRequest() *http.Request
+    GetRequest returns the original http.Request object, for debugging purposes
+
+func (dsfr *DynamicSniffForwardRequest) GetRequestUUID() string
+    GetRequestUUID returns the request UUID if this UUID is empty string,
+    that might indicate the request is not coming from the dynamic router
+
+type IntroSpect struct {
+	//  Plugin metadata
+	ID            string     `json:"id"`             //Unique ID of your plugin, recommended using your own domain in reverse like com.yourdomain.pluginname
+	Name          string     `json:"name"`           //Name of your plugin
+	Author        string     `json:"author"`         //Author name of your plugin
+	AuthorContact string     `json:"author_contact"` //Author contact of your plugin, like email
+	Description   string     `json:"description"`    //Description of your plugin
+	URL           string     `json:"url"`            //URL of your plugin
+	Type          PluginType `json:"type"`           //Type of your plugin, Router(0) or Utilities(1)
+	VersionMajor  int        `json:"version_major"`  //Major version of your plugin
+	VersionMinor  int        `json:"version_minor"`  //Minor version of your plugin
+	VersionPatch  int        `json:"version_patch"`  //Patch version of your plugin
+
+	//		Static Capture Settings
+	//
+	//		Once plugin is enabled these rules always applies to the enabled HTTP Proxy rule
+	//		This is faster than dynamic capture, but less flexible
+
+	StaticCapturePaths   []StaticCaptureRule `json:"static_capture_paths"`   //Static capture paths of your plugin, see Zoraxy documentation for more details
+	StaticCaptureIngress string              `json:"static_capture_ingress"` //Static capture ingress path of your plugin (e.g. /s_handler)
+
+	//		Dynamic Capture Settings
+	//
+	//		Once plugin is enabled, these rules will be captured and forward to plugin sniff
+	//		if the plugin sniff returns 280, the traffic will be captured
+	//		otherwise, the traffic will be forwarded to the next plugin
+	//		This is slower than static capture, but more flexible
+
+	DynamicCaptureSniff   string `json:"dynamic_capture_sniff"`   //Dynamic capture sniff path of your plugin (e.g. /d_sniff)
+	DynamicCaptureIngress string `json:"dynamic_capture_ingress"` //Dynamic capture ingress path of your plugin (e.g. /d_handler)
+
+	//  UI Path for your plugin
+	UIPath string `json:"ui_path"` //UI path of your plugin (e.g. /ui), will proxy the whole subpath tree to Zoraxy Web UI as plugin UI
+
+	//  Subscriptions Settings
+	SubscriptionPath    string            `json:"subscription_path"`    //Subscription event path of your plugin (e.g. /notifyme), a POST request with SubscriptionEvent as body will be sent to this path when the event is triggered
+	SubscriptionsEvents map[string]string `json:"subscriptions_events"` //Subscriptions events of your plugin, see Zoraxy documentation for more details
+}
+    IntroSpect Payload
+
+    When the plugin is initialized with -introspect flag, the plugin shell
+    return this payload as JSON and exit
+
+type PathRouter struct {
+	// Has unexported fields.
+}
+
+func NewPathRouter() *PathRouter
+    NewPathRouter creates a new PathRouter
+
+func (p *PathRouter) PrintRequestDebugMessage(r *http.Request)
+
+func (p *PathRouter) RegisterDynamicCaptureHandle(capture_ingress string, mux *http.ServeMux, handlefunc func(http.ResponseWriter, *http.Request))
+    RegisterDynamicCaptureHandle register the dynamic capture ingress path with
+    a handler
+
+func (p *PathRouter) RegisterDynamicSniffHandler(sniff_ingress string, mux *http.ServeMux, handler SniffHandler)
+    RegisterDynamicSniffHandler registers a dynamic sniff handler for a path
+    You can decide to accept or skip the request based on the request header and
+    paths
+
+func (p *PathRouter) RegisterPathHandler(path string, handler http.Handler)
+    RegisterPathHandler registers a handler for a path
+
+func (p *PathRouter) RegisterStaticCaptureHandle(capture_ingress string, mux *http.ServeMux)
+    StartStaticCapture starts the static capture ingress
+
+func (p *PathRouter) RemovePathHandler(path string)
+    RemovePathHandler removes a handler for a path
+
+func (p *PathRouter) SetDebugPrintMode(enable bool)
+    SetDebugPrintMode sets the debug print mode
+
+func (p *PathRouter) SetDefaultHandler(handler http.Handler)
+    SetDefaultHandler sets the default handler for the router This handler will
+    be called if no path handler is found
+
+type PluginType int
+
+const (
+	PluginType_Router    PluginType = 0 //Router Plugin, used for handling / routing / forwarding traffic
+	PluginType_Utilities PluginType = 1 //Utilities Plugin, used for utilities like Zerotier or Static Web Server that do not require interception with the dpcore
+)
+type PluginUiDebugRouter struct {
+	PluginID      string //The ID of the plugin
+	TargetDir     string //The directory where the UI files are stored
+	HandlerPrefix string //The prefix of the handler used to route this router, e.g. /ui
+	EnableDebug   bool   //Enable debug mode
+	// Has unexported fields.
+}
+
+func NewPluginFileSystemUIRouter(pluginID string, targetDir string, handlerPrefix string) *PluginUiDebugRouter
+    NewPluginFileSystemUIRouter creates a new PluginUiRouter with file system
+    The targetDir is the directory where the UI files are stored (e.g. ./www)
+    The handlerPrefix is the prefix of the handler used to route this router
+    The handlerPrefix should start with a slash (e.g. /ui) that matches the
+    http.Handle path All prefix should not end with a slash
+
+func (p *PluginUiDebugRouter) AttachHandlerToMux(mux *http.ServeMux)
+    Attach the file system UI handler to the target http.ServeMux
+
+func (p *PluginUiDebugRouter) Handler() http.Handler
+    GetHttpHandler returns the http.Handler for the PluginUiRouter
+
+func (p *PluginUiDebugRouter) RegisterTerminateHandler(termFunc func(), mux *http.ServeMux)
+    RegisterTerminateHandler registers the terminate handler for the
+    PluginUiRouter The terminate handler will be called when the plugin is
+    terminated from Zoraxy plugin manager if mux is nil, the handler will be
+    registered to http.DefaultServeMux
+
+type PluginUiRouter struct {
+	PluginID       string    //The ID of the plugin
+	TargetFs       *embed.FS //The embed.FS where the UI files are stored
+	TargetFsPrefix string    //The prefix of the embed.FS where the UI files are stored, e.g. /web
+	HandlerPrefix  string    //The prefix of the handler used to route this router, e.g. /ui
+	EnableDebug    bool      //Enable debug mode
+	// Has unexported fields.
+}
+
+func NewPluginEmbedUIRouter(pluginID string, targetFs *embed.FS, targetFsPrefix string, handlerPrefix string) *PluginUiRouter
+    NewPluginEmbedUIRouter creates a new PluginUiRouter with embed.FS The
+    targetFsPrefix is the prefix of the embed.FS where the UI files are stored
+    The targetFsPrefix should be relative to the root of the embed.FS The
+    targetFsPrefix should start with a slash (e.g. /web) that corresponds to the
+    root folder of the embed.FS The handlerPrefix is the prefix of the handler
+    used to route this router The handlerPrefix should start with a slash (e.g.
+    /ui) that matches the http.Handle path All prefix should not end with a
+    slash
+
+func (p *PluginUiRouter) AttachHandlerToMux(mux *http.ServeMux)
+    Attach the embed UI handler to the target http.ServeMux
+
+func (p *PluginUiRouter) Handler() http.Handler
+    GetHttpHandler returns the http.Handler for the PluginUiRouter
+
+func (p *PluginUiRouter) RegisterTerminateHandler(termFunc func(), mux *http.ServeMux)
+    RegisterTerminateHandler registers the terminate handler for the
+    PluginUiRouter The terminate handler will be called when the plugin is
+    terminated from Zoraxy plugin manager if mux is nil, the handler will be
+    registered to http.DefaultServeMux
+
+type RuntimeConstantValue struct {
+	ZoraxyVersion    string `json:"zoraxy_version"`
+	ZoraxyUUID       string `json:"zoraxy_uuid"`
+	DevelopmentBuild bool   `json:"development_build"` //Whether the Zoraxy is a development build or not
+}
+
+type SniffHandler func(*DynamicSniffForwardRequest) SniffResult
+
+type SniffResult int
+
+const (
+	SniffResultAccpet SniffResult = iota // Forward the request to this plugin dynamic capture ingress
+	SniffResultSkip                      // Skip this plugin and let the next plugin handle the request
+)
+type StaticCaptureRule struct {
+	CapturePath string `json:"capture_path"`
+}
+
+type SubscriptionEvent struct {
+	EventName   string `json:"event_name"`
+	EventSource string `json:"event_source"`
+	Payload     string `json:"payload"` //Payload of the event, can be empty
+}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Zoraxy © tobychui + + 2025 + +
+
+
+ + + + \ No newline at end of file diff --git a/docs/plugins/index.json b/docs/plugins/index.json index 852c6d6..5dc0a19 100644 --- a/docs/plugins/index.json +++ b/docs/plugins/index.json @@ -103,6 +103,11 @@ "filename": "index.md", "title": "index", "type": "file" + }, + { + "filename": "zoraxy_plugin API.md", + "title": "zoraxy_plugin API", + "type": "file" } ] } \ No newline at end of file diff --git a/docs/plugins/template/documents.html b/docs/plugins/template/documents.html index e5dc8c9..f552182 100644 --- a/docs/plugins/template/documents.html +++ b/docs/plugins/template/documents.html @@ -71,8 +71,8 @@ Documents - - Examples + + Examples