Introduction
What is Zoraxy Plugin?
Zoraxy Plugin is a powerful extension feature designed to enhance the functionality of the Zoraxy system. It provides additional features and capabilities that are not part of the core system, allowing users to customize their experience and optimize performance. The plugin is built to be modular and flexible, enabling users to tailor their Zoraxy environment to meet specific needs.
Zoraxy plugins are distributed as binaries, and developers have the flexibility to choose whether to open source them or not
as the plugin library and interface are open source under the LGPL license.
There are two primary types of plugins: router and utilities. Router-type plugins are involved with connections from HTTP proxy rules,
while utility plugins provide user interfaces for various network features that operate independently of the Zoraxy core.
How plugins are distributed & installed
Zoraxy plugins are distributed as platform-dependent binaries, making them tailored to specific operating systems and CPU architectures.
These binaries are named following a convention that includes the operating system, CPU architecture, and plugin name, such as linux_amd64_foobar, windows_amd64_foobar.exe, or linux_arm64_foobar.
To manually install a plugins for testing, simply place the binary file into the /plugins/{plugin_name}/ folder within your Zoraxy installation directory.
Warning: The binary name inside the folder must match the plugin folder name. For example, the binary should be named foobar (or foobar.exe on Windows) if placed in the /plugins/foobar/ folder. Avoid using names like foobar_plugin.exe.
For distribution, a plugin store system is used. The plugin store architecture is similar to the one built into the Arduino IDE, with a manager URL (a JSON file) where all the plugins supported by that store will be listed. See the documentation section for more details on how to implement your own plugin store.
Plugin vs Pull Request
The Zoraxy plugin was introduced to address specific use cases that enhance its functionality. It serves as an extension to the core Zoraxy system, providing additional features and capabilities while maintaining the integrity of the core system.
- It is designed to handle features that are challenging to integrate directly into the Zoraxy core.
- It caters to scenarios where certain features are only applicable in limited situations, avoiding unnecessary resource consumption for other users.
- The plugin allows for frequent updates to specific code components without impacting the core's stability or causing downtime.
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.
FAQ
What skills do I need for developing a plugin?
Basic HTML, JavaScript, and CSS skills are required, with Go (Golang) being the preferred backend language. However, any programming language that can be compiled into a binary and provide a web server interface will work.
Will a plugin crash the whole Zoraxy?
No. Plugins operate in a separate process from Zoraxy. If a plugin crashes, Zoraxy will terminate and disable that plugin without affecting the core operations. This is by design to ensure stability.
Can I sell my plugin?
Yes, the plugin library and interface design are open source under the LGPL license. You are not required to disclose the source code of your plugin as long as you do not modify the plugin library and use it as-is. For more details on how to comply with the license, refer to the licensing documentation.
How can I add my plugin to the official plugin store?
To add your plugin to the official plugin store, open a pull request (PR) in the plugin repository.
Ready to start developing your own plugin?
Begin your journey by exploring the plugin development documentation and setting up your development environment.