[PR #5120] [CLOSED] feat: Add ProxyStarted webhook event for dynamic port notification #5137

New issue

Closed

opened 2026-05-05 14:55:23 -06:00 by gitea-mirror · 0 comments

gitea-mirror commented

2026-05-05 14:55:23 -06:00

Owner

📋 Pull Request Information

Original PR: https://github.com/fatedier/frp/pull/5120
Author: @sripriya3191
Created: 1/9/2026
Status: ❌ Closed

Base: dev ← Head: feature/proxy-started-webhook

📝 Commits (1)

3260d91 feat: add ProxyStarted webhook event with allocated port

📊 Changes

6 files changed (+101 additions, -19 deletions)

View changed files

📝 doc/server_plugin.md (+23 -1)
📝 pkg/config/v1/validation/validation.go (+1 -0)
📝 pkg/plugin/server/manager.go (+45 -12)
📝 pkg/plugin/server/plugin.go (+7 -6)
📝 pkg/plugin/server/types.go (+10 -0)
📝 server/control.go (+15 -0)

📄 Description

Summary

Add a new ProxyStarted server plugin webhook event that fires after a proxy has been successfully started and port allocation is complete.

Problem

The existing NewProxy webhook event fires before port allocation occurs. This means:

When using remotePort = 0 for dynamic port allocation, the webhook only receives remote_port: 0
External systems cannot know the actual allocated port via webhooks
Users must poll the admin API or wait for NewUserConn events to discover the negotiated port

Solution

Add a new ProxyStarted webhook event that:

Fires immediately after successful proxy registration and port allocation
Includes remote_addr with the actual allocated port (e.g., :10000)
Is a notification-only event (fire and forget) - plugins cannot reject since the proxy is already running
Follows the same pattern as CloseProxy for consistency

Use Cases

Service Discovery: Register dynamically allocated ports with service discovery systems (Consul, etcd, etc.)
DNS Updates: Automatically update DNS records when proxies start
Monitoring: Track proxy lifecycle with actual port information
Audit Logging: Complete audit trail including negotiated ports

Changes

pkg/plugin/server/types.go - Add ProxyStartedContent type
pkg/plugin/server/plugin.go - Add OpProxyStarted constant
pkg/plugin/server/manager.go - Add proxyStartedPlugins slice and ProxyStarted() method
pkg/config/v1/validation/validation.go - Add ProxyStarted to SupportedHTTPPluginOps
server/control.go - Call ProxyStarted webhook after successful proxy registration
doc/server_plugin.md - Update documentation

Configuration

# frps.toml
[[httpPlugins]]
name = "port-notifier"
addr = "127.0.0.1:9000"
path = "/handler"
ops = ["ProxyStarted"]

Webhook Payload

{
    "version": "0.1.0",
    "op": "ProxyStarted",
    "content": {
        "user": {
            "user": "myuser",
            "metas": {"key": "value"},
            "run_id": "abc123"
        },
        "proxy_name": "my-tcp-proxy",
        "proxy_type": "tcp",
        "remote_addr": ":10000"
    }
}

Comparison: NewProxy vs ProxyStarted

Event	When Fired	`remote_port` / `remote_addr`	Can Reject?
`NewProxy`	Before port allocation	Requested port (may be 0)	Yes
`ProxyStarted`	After port allocation	Actual allocated port	No

Backward Compatibility

This is a purely additive change:

No existing behavior is modified
New event is opt-in via plugin configuration
Existing plugins continue to work unchanged

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/fatedier/frp/pull/5120 **Author:** [@sripriya3191](https://github.com/sripriya3191) **Created:** 1/9/2026 **Status:** ❌ Closed **Base:** `dev` ← **Head:** `feature/proxy-started-webhook` --- ### 📝 Commits (1) - [`3260d91`](https://github.com/fatedier/frp/commit/3260d918eac01471b786e421860c5e1ceba5e35b) feat: add ProxyStarted webhook event with allocated port ### 📊 Changes **6 files changed** (+101 additions, -19 deletions) <details> <summary>View changed files</summary> 📝 `doc/server_plugin.md` (+23 -1) 📝 `pkg/config/v1/validation/validation.go` (+1 -0) 📝 `pkg/plugin/server/manager.go` (+45 -12) 📝 `pkg/plugin/server/plugin.go` (+7 -6) 📝 `pkg/plugin/server/types.go` (+10 -0) 📝 `server/control.go` (+15 -0) </details> ### 📄 Description ## Summary Add a new `ProxyStarted` server plugin webhook event that fires **after** a proxy has been successfully started and port allocation is complete. ## Problem The existing `NewProxy` webhook event fires **before** port allocation occurs. This means: - When using `remotePort = 0` for dynamic port allocation, the webhook only receives `remote_port: 0` - External systems cannot know the actual allocated port via webhooks - Users must poll the admin API or wait for `NewUserConn` events to discover the negotiated port ## Solution Add a new `ProxyStarted` webhook event that: - Fires immediately after successful proxy registration and port allocation - Includes `remote_addr` with the actual allocated port (e.g., `:10000`) - Is a notification-only event (fire and forget) - plugins cannot reject since the proxy is already running - Follows the same pattern as `CloseProxy` for consistency ## Use Cases 1. **Service Discovery**: Register dynamically allocated ports with service discovery systems (Consul, etcd, etc.) 2. **DNS Updates**: Automatically update DNS records when proxies start 3. **Monitoring**: Track proxy lifecycle with actual port information 4. **Audit Logging**: Complete audit trail including negotiated ports ## Changes - `pkg/plugin/server/types.go` - Add `ProxyStartedContent` type - `pkg/plugin/server/plugin.go` - Add `OpProxyStarted` constant - `pkg/plugin/server/manager.go` - Add `proxyStartedPlugins` slice and `ProxyStarted()` method - `pkg/config/v1/validation/validation.go` - Add `ProxyStarted` to `SupportedHTTPPluginOps` - `server/control.go` - Call `ProxyStarted` webhook after successful proxy registration - `doc/server_plugin.md` - Update documentation ## Configuration ```toml # frps.toml [[httpPlugins]] name = "port-notifier" addr = "127.0.0.1:9000" path = "/handler" ops = ["ProxyStarted"] ``` ## Webhook Payload ```json { "version": "0.1.0", "op": "ProxyStarted", "content": { "user": { "user": "myuser", "metas": {"key": "value"}, "run_id": "abc123" }, "proxy_name": "my-tcp-proxy", "proxy_type": "tcp", "remote_addr": ":10000" } } ``` ## Comparison: NewProxy vs ProxyStarted | Event | When Fired | `remote_port` / `remote_addr` | Can Reject? | |-------|------------|-------------------------------|-------------| | `NewProxy` | Before port allocation | Requested port (may be 0) | Yes | | `ProxyStarted` | After port allocation | Actual allocated port | No | ## Backward Compatibility This is a purely additive change: - No existing behavior is modified - New event is opt-in via plugin configuration - Existing plugins continue to work unchanged --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>