ngrok is Deprecating Edges in Favor of Endpoints

[alexdlaird]

ngrok has deprecating Edges, will remove support on December 31st, 2025. java-ngrok supports Labeled Tunnels (on Edges) in the config file, the documented replacement for which is Internal Endpoints. We should investigate further if we should add native support for either Internal Endpoints or Cloud Endpoints, or how that would work with java-ngrok.

Some reference to Edges and Labeled Tunnels exists in the docs and should be removed along with the dead code, once we approach the sunset date.

These are the tasks that will need to be completed, then we will need to bump the major version to release these breaking changes:

• Update documentation to reference deprecation of Edges and Labeled Tunnels.
• Rebase main to 1.4.x branch. Since Edge was a feature we did backport to the Java 8 version of the library, we should also backport the deprecation of the feature (and in doing so, also bring the latest and greatest features back to the Java 8 release).
• Release a patch version to Java 8-compatible 1.4.x with the deprecation notice.
• Release a patch version to 2.3.x with the deprecation notice so users who continue pinning back that version will know these features will no longer supported by ngrok (since the core of everything else in that version should continue to work fine).
• Remove code and documentation around applyEdgeToTunnel, and other Edge/Labeled Tunnels-related code.
• Investigate Internal Endpoints and Cloud Endpoints, document current support and migration from Edges (if applicable) in this ticket.

[alexdlaird]

With Internal Endpoints being the replacement for Labeled Tunnels (on Edges), it this guide the natural replacement for that functionality. Namely:

1. Create an Internal Endpoint
2. Create a domain
3. Create a Traffic Policy pointing to the Internal Endpoint
4. Create a Cloud Endpoint using the Traffic Policy

The guide has you issue this Agent CLI command:

ngrok http 80  --url https://your-domain-name.internal

The equivalent in java-ngrok would be:

final NgrokClient ngrokClient = new NgrokClient.Builder().build();

final CreateTunnel endpointInternal = new CreateTunnel.Builder()
        .withDomain("your-domain-name.internal")
        .build();
ngrokClient.connect(endpointInternal);

Providing a domain suffix of .internal always applies the internal binding to a tunnel, which is a useful trick the ngrok Agent now gives us. The internal endpoint is now online, visible on the ngrok Dashboard, and accessible internally to other ngrok clients. If you follow the rest of the guide linked above, you can then map this Internal (Agent) Endpoint to a Cloud Endpoint, add load balancing, etc.

Similarly, you could define this endpoint from the config file (but using v2 tunnels definitions rather than endpoints):

tunnels:
    your-endpoint-name:
        proto: http
        addr: 80
        domain: your-domain-name.internal

final NgrokClient ngrokClient = new NgrokClient.Builder().build();

final CreateTunnel endpointInternal = new CreateTunnel.Builder()
        .withName("your-domain-name")
        .build();
ngrokClient.connect(endpointInternal);

In these ways, support for Endpoints—and a migration strategy away from Edges—already exists in java-ngrok.

[alexdlaird]

To make support for Endpoints more robust in the future, we could consider adding the following:

• Support for interpolating endpoints from the v3 config (similar to how we did for labels with applyEdgeToTunnel())—this doesn't seem like it will become pressing though until ngrok creates a config v4 that actually removes support for tunnels definitions (which we don't have a timeline for if/when they would do).
• Support for using the Agent's ngrok api CLI commands, allowing users to programmatically follow steps 2 and 4 in the guide linked above—this seems like a "nice to have" and also not pressing.