Packaging & Publishing

Once your plugin passes unit tests and handles protocol streams correctly, you can package, test, and distribute it to other servers and teams.

---

1. Local Testing with TCP Warden

Test your plugin end-to-end on your local machine before committing code:

# 1. Install local plugin into tcp-wardentcp-warden plugins install ./echo_guard# 2. Verify it appears as ACTIVEtcp-warden plugins list# 3. Validate configuration syntaxtcp-warden validate --config tcp-warden.yaml# 4. Start the proxytcp-warden run --config tcp-warden.yaml

---

2. Distributing via Git

You can host plugins in any Git repository (GitHub, GitLab, self-hosted Gitea). TCP Warden pulls the repository, verifies the manifest, compiles the plugin, and runs tests automatically:

# Install directly from a public or private Git repositorytcp-warden plugins install https://github.com/my-org/my-protocol-guard# Or declare in tcp-warden.yaml for auto-installation on bootplugins:  my_guard:    enabled: true    source: "https://github.com/my-org/my-protocol-guard"

---

3. Versioning & Git Tags

Plugin versions follow standard Semantic Versioning (MAJOR.MINOR.PATCH). To publish a new version of your plugin:

1. Bump the version field in plugin.yaml (e.g., version: "1.0.0").
2. Commit your changes and push a Git tag:

# 1. Update version in plugin.yaml:#    version: "1.0.0"# 2. Commit and create a Git release taggit commit -am "chore: release v1.0.0"git tag v1.0.0git push origin v1.0.0

Users installing your plugin can pin to specific tags, branches, or commit hashes directly in their tcp-warden.yaml configuration.

---

4. Pre-Publication Checklist

Before tagging a release or submitting a plugin to the official registry, review this checklist:

Item	Requirement	Why It Matters
Embedded Manifest	Uses //go:embed plugin.yaml and sdk.MustParseManifest.	Eliminates loose file dependencies at runtime.
Manifest Version	Sets manifest_version: "1.0.0".	Ensures compatibility with the TCP Warden Plugin SDK.
Buffer Preservation	Wraps read sockets in &protocol.BufferedConn{}.	Prevents silent data corruption and dropped handshake bytes.
Auth Failure Reporting	Calls ctx.OnAuthFailure() on bad logins.	Feeds TCP Warden's automated sliding-window ban engine.
Security Auditing	Calls ctx.OnSecurityEvent() on blocked attacks.	Enables real-time SSE streaming and CrowdSec log ingestion.
Bounded Reads	Implements max buffer limits when reading sockets.	Prevents out-of-memory crashes from malicious oversized packets.
Multithreading Safety	go test -race -count=1 ./... passes cleanly.	Guarantees zero race conditions under high concurrent loads.

---

Contributing to Official Plugins

To contribute your plugin to the official routewarden/plugins repository:

1. Ensure all tests in your plugin pass with -race.
2. Follow the directory layout: plugin.yaml, plugin.go, inspector.go, plugin_test.go, and README.md.
3. Open a Pull Request against routewarden/plugins. Once merged, users can install your plugin instantly using tcp-warden plugins install <name>.