Introspect

Last Update: 25/05/2025

Introspect, similar to the one in dbus design, is used to get the information from plugin when Zoraxy starts (or manually triggered in development mode or force reload plugin list).

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.

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

	/*

		Endpoint Settings

	*/

	/*
		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
}

The introspect provide Zoraxy the required information to start the plugin and how to interact with it. For more details on what those capture settings are for, see “Capture Mode” section.

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.

$ ./debugger -introspect
{
 "id": "org.aroz.zoraxy.debugger",
 "name": "Plugin Debugger",
 "author": "aroz.org",
 "author_contact": "https://aroz.org",
 "description": "A debugger for Zoraxy \u003c-\u003e plugin communication pipeline",
 "url": "https://zoraxy.aroz.org",
 "type": 0,
 "version_major": 1,
 "version_minor": 0,
 "version_patch": 0,
 "static_capture_paths": [
  {
   "capture_path": "/test_a"
  },
  {
   "capture_path": "/test_b"
  }
 ],
 "static_capture_ingress": "/s_capture",
 "dynamic_capture_sniff": "/d_sniff",
 "dynamic_capture_ingress": "/d_capture",
 "ui_path": "/debug",
 "subscription_path": "",
 "subscriptions_events": null
}