Skip to content

Conversation

@sripriya3191
Copy link

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

# 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

Add a new ProxyStarted webhook event that fires after a proxy has been
successfully started and port allocation is complete. This allows
external systems to receive the actual allocated port, which is
especially useful when remotePort=0 is used for dynamic port allocation.

Changes:
- Add ProxyStartedContent type in pkg/plugin/server/types.go
- Add OpProxyStarted constant in pkg/plugin/server/plugin.go
- Add ProxyStarted method to Manager in pkg/plugin/server/manager.go
- Add ProxyStarted to supported operations in validation
- Call ProxyStarted webhook after successful proxy registration
- Update documentation in doc/server_plugin.md
@fatedier
Copy link
Owner

We’re not going to accept this PR.

The actual assigned port/address can already be retrieved via the frps API.

@sripriya3191
Copy link
Author

Thank you for the suggestion to use the frps API. While that's a valid approach, I really like the existing server-side plugin/hook functionality and thought this would be a natural extension to allow external services to be notified of allocated ports in real time. Let us know your thoughts!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants