# 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.

# 介紹

## Zoraxy 插件是什麼？

Zoraxy 插件是一個強大的擴展功能，旨在增強 Zoraxy 系統的功能。 它提供了核心系統中沒有的額外功能和能力，允許用戶自定義體驗並優化性能。 該插件被設計為模組化且靈活的，使用戶能夠根據特定需求調整 Zoraxy 環境。

Zoraxy 插件以二進制文件的形式分發，開發者可以選擇是否開源 因為插件庫和接口是基於 LGPL 授權的開源項目。
插件主要分為兩種類型：路由器和工具。路由器類型的插件與 HTTP 代理規則的連接有關， 而工具插件則為各種獨立於 Zoraxy 核心運行的網絡功能提供用戶界面。

## 插件如何分發與安裝

Zoraxy 插件以平台相關的二進制文件形式分發，這使得它們針對特定的操作系統和 CPU 架構進行了優化。 這些二進制文件的命名遵循一個約定，包括操作系統、CPU 架構和插件名稱，例如 linux_amd64_foobar、windows_amd64_foobar.exe 或 linux_arm64_foobar。
要手動安裝插件進行測試，只需將二進制文件放置在 Zoraxy 安裝目錄中的 /plugins/{plugin_name}/ 文件夾內。

警告： 文件夾內的二進制文件名稱必須與插件文件夾名稱匹配。 例如，二進制文件應命名為 foobar（或在 Windows 上為 foobar.exe）， 如果放置在 /plugins/foobar/ 文件夾中。 請避免使用類似 foobar_plugin.exe 的名稱。

在分發方面，使用了一個插件商店系統。該插件商店的架構類似於 Arduino IDE 中內置的系統， 包括一個管理器 URL（JSON 文件），其中列出了該商店支持的所有插件。 有關如何實現自己的插件商店的更多詳細信息，請參閱文檔部分。

## 插件與開 Pull Request 的區別

Zoraxy 插件的引入是為了解決特定的使用案例，從而增強其功能。 它作為 Zoraxy 核心系統的擴展，提供了額外的功能和能力，同時保持核心系統的完整性。

- 它旨在處理難以直接集成到 Zoraxy 核心中的功能。
- 它適用於某些功能僅在有限情況下適用的場景，避免了對其他用戶造成不必要的資源消耗。
- 插件允許對特定代碼組件進行頻繁更新，而不影響核心的穩定性或導致停機。

### 何時應該新增核心 PR 或插件？

在某些情況下，將功能實作為插件比直接整合到 Zoraxy 核心更為合理：

- 核心 PR： 如果功能對大多數用戶都有相關性，並且能提升 Zoraxy 的核心功能，則應考慮提交核心的 Pull Request (PR)。
- 插件： 如果功能僅針對少數用戶群體，或需要額外的依賴項而非所有用戶都需要，則應開發為插件。

決策取決於功能的普遍相關性及對核心穩定性的影響。插件提供了靈活性，且不會對核心造成負擔。

## 常見問題

### 開發插件需要什麼技能？

需要基本的 HTML、JavaScript 和 CSS 技能，後端語言首選 Go（Golang）。然而，任何可以編譯成二進制文件並提供 Web 服務器接口的編程語言都可以使用。

### 插件會導致整個 Zoraxy 崩潰嗎？

不會。插件在與 Zoraxy 分離的進程中運行。如果插件崩潰，Zoraxy 會終止並禁用該插件，而不會影響核心操作。這是為了確保穩定性而設計的。

### 我可以出售我的插件嗎？

可以，插件庫和接口設計是基於 LGPL 授權的開源項目。只要您不修改插件庫並按原樣使用它，就不需要公開插件的源代碼。關於如何遵守許可證的更多詳細信息，請參閱許可證文檔。

### 如何將我的插件添加到官方插件商店？

要將您的插件添加到官方插件商店，請在插件存儲庫中提交一個拉取請求（PR）。

## 準備好開始開發自己的插件了嗎？

通過探索插件開發文檔並設置您的開發環境，開始您的旅程。

# Einführung

## Was ist das Zoraxy Plugin?

Das Zoraxy Plugin ist eine leistungsstarke Erweiterungsfunktion, die entwickelt wurde, um die Funktionalität des Zoraxy-Systems zu verbessern. Es bietet zusätzliche Funktionen und Fähigkeiten, die nicht Teil des Kernsystems sind, und ermöglicht es den Benutzern, ihre Erfahrung anzupassen und die Leistung zu optimieren. Das Plugin ist modular und flexibel aufgebaut, sodass Benutzer ihre Zoraxy-Umgebung an spezifische Anforderungen anpassen können.

Zoraxy-Plugins werden als Binärdateien verteilt, und Entwickler können wählen, ob sie diese als Open Source veröffentlichen möchten oder nicht, da die Plugin-Bibliothek und die Schnittstelle unter der LGPL-Lizenz Open Source sind.
Es gibt zwei Haupttypen von Plugins: Router und Utilities. Router-Plugins sind an Verbindungen von HTTP-Proxy-Regeln beteiligt, während Utility-Plugins Benutzeroberflächen für verschiedene Netzwerkfunktionen bereitstellen, die unabhängig vom Zoraxy-Kern arbeiten.

## Wie Plugins verteilt und installiert werden

Zoraxy-Plugins werden als plattformabhängige Binärdateien verteilt, die speziell für bestimmte Betriebssysteme und CPU-Architekturen optimiert sind. Diese Binärdateien werden nach einem Konventionsschema benannt, das das Betriebssystem, die CPU-Architektur und den Plugin-Namen umfasst, wie z. B. linux_amd64_foobar, windows_amd64_foobar.exe oder linux_arm64_foobar.
Um ein Plugin manuell zu installieren und zu testen, legen Sie die Binärdatei einfach im Ordner /plugins/{plugin_name}/ im Zoraxy-Installationsverzeichnis ab.

Warnung: Der Name der Binärdatei im Ordner muss mit dem Plugin-Ordnernamen übereinstimmen. Beispielsweise sollte die Binärdatei foobar (oder foobar.exe unter Windows) heißen, wenn sie im Ordner /plugins/foobar/ abgelegt wird. Vermeiden Sie Namen wie foobar_plugin.exe.

Für die Verteilung wird ein Plugin-Store-System verwendet. Die Architektur des Plugin-Stores ähnelt der des Arduino IDE, mit einer Manager-URL (einer JSON-Datei), in der alle von diesem Store unterstützten Plugins aufgelistet sind. Weitere Details zur Implementierung eines eigenen Plugin-Stores finden Sie im Dokumentationsabschnitt.

## Plugin vs Pull Request

Das Zoraxy-Plugin wurde eingeführt, um spezifische Anwendungsfälle zu adressieren, die seine Funktionalität erweitern. Es dient als Erweiterung des Zoraxy-Kernsystems und bietet zusätzliche Funktionen und Fähigkeiten, während die Integrität des Kernsystems erhalten bleibt.

- Es ist darauf ausgelegt, Funktionen zu behandeln, die schwer direkt in den Zoraxy-Kern zu integrieren sind.
- Es richtet sich an Szenarien, in denen bestimmte Funktionen nur in begrenzten Situationen anwendbar sind, um unnötigen Ressourcenverbrauch für andere Benutzer zu vermeiden.
- Das Plugin ermöglicht häufige Updates spezifischer Codekomponenten, ohne die Stabilität des Kerns zu beeinträchtigen oder Ausfallzeiten zu verursachen.

### Wann sollte ein Core-PR oder ein Plugin hinzugefügt werden?

In bestimmten Situationen ist es sinnvoller, eine Funktion als Plugin zu implementieren, anstatt sie direkt in den Zoraxy-Kern zu integrieren:

- Core-PR: Wenn die Funktion für die meisten Benutzer relevant ist und die Kernfunktionalität von Zoraxy verbessert, sollten Sie einen Core-Pull-Request (PR) in Betracht ziehen.
- Plugin: Wenn die Funktion auf eine kleinere Benutzerbasis abzielt oder zusätzliche Abhängigkeiten erfordert, die nicht alle Benutzer benötigen, sollte sie als Plugin entwickelt werden.

Die Entscheidung hängt von der allgemeinen Relevanz der Funktion und ihrer Auswirkung auf die Stabilität des Kerns ab. Plugins bieten Flexibilität, ohne den Kern zu belasten.

## FAQ

### Welche Fähigkeiten benötige ich, um ein Plugin zu entwickeln?

Grundlegende Kenntnisse in HTML, JavaScript und CSS sind erforderlich, wobei Go (Golang) die bevorzugte Backend-Sprache ist. Allerdings kann jede Programmiersprache verwendet werden, die in eine Binärdatei kompiliert werden kann und eine Webserver-Schnittstelle bereitstellt.

### Wird ein Plugin das gesamte Zoraxy zum Absturz bringen?

Nein. Plugins laufen in einem separaten Prozess von Zoraxy. Wenn ein Plugin abstürzt, beendet und deaktiviert Zoraxy dieses Plugin, ohne die Kernoperationen zu beeinträchtigen. Dies ist so konzipiert, um Stabilität zu gewährleisten.

### Kann ich mein Plugin verkaufen?

Ja, die Plugin-Bibliothek und das Schnittstellendesign sind unter der LGPL-Lizenz Open Source. Sie sind nicht verpflichtet, den Quellcode Ihres Plugins offenzulegen, solange Sie die Plugin-Bibliothek nicht ändern und sie wie vorgesehen verwenden. Weitere Details zur Einhaltung der Lizenz finden Sie in der Lizenzdokumentation.

### Wie kann ich mein Plugin zum offiziellen Plugin-Store hinzufügen?

Um Ihr Plugin zum offiziellen Plugin-Store hinzuzufügen, öffnen Sie eine Pull-Request (PR) im Plugin-Repository.

## Bereit, Ihr eigenes Plugin zu entwickeln?

Beginnen Sie Ihre Reise, indem Sie die Plugin-Entwicklungsdokumentation erkunden und Ihre Entwicklungsumgebung einrichten.