Class NgrokClient
- java.lang.Object
-
- com.github.alexdlaird.ngrok.NgrokClient
-
public class NgrokClient extends java.lang.Object
A client for interacting with ngrok, its binary, and its APIs. Can be configured withJavaNgrokConfig
.Open a Tunnel
To open a tunnel, use theNgrokClient.connect()
method, which returns aTunnel
, and this returned object has a reference to the public URL generated byngrok
in itsTunnel.getPublicUrl()
method.final NgrokClient ngrokClient = new NgrokClient.Builder().build(); // Open a HTTP tunnel on the default port 80 // <Tunnel: "http://<public_sub>.ngrok.io" -> "http://localhost:80"> final Tunnel httpTunnel = ngrokClient.connect(); // Open a SSH tunnel // <Tunnel: "tcp://0.tcp.ngrok.io:12345" -> "localhost:22"> final CreateTunnel sshCreateTunnel = new CreateTunnel.Builder() .withProto(Proto.TCP) .withAddr(22) .build(); final Tunnel sshTunnel = ngrokClient.connect(sshCreateTunnel); // Open a tunnel to MySQL with a Reserved TCP Address // <NgrokTunnel: "tcp://1.tcp.ngrok.io:12345" -> "localhost:3306"> final CreateTunnel mysqlCreateTunnel = new CreateTunnel.Builder() .withProto(Proto.TCP) .withAddr(3306) .withRemoteAddr("1.tcp.ngrok.io:12345") .build(); final Tunnel mysqlTunnel = ngrokClient.connect(mysqlCreateTunnel); // Open a tunnel to a local file server // <NgrokTunnel: "http://<public_sub>.ngrok.io" -> "file:///"> final CreateTunnel fileserverCreateTunnel = new CreateTunnel.Builder() .withAddr("file:///) .build(); final Tunnel fileserverTunnel = ngrokClient.connect(fileserverCreateTunnel);
The
NgrokClient.connect()
method can also take aCreateTunnel
(which can be built throughits Builder
) that allows us to pass additional properties that are supported by ngrok.Note:
ngrok
's default behavior forhttp
when no additional properties are passed is to open two tunnels, onehttp
and onehttps
. This method will return a reference to thehttp
tunnel in this case. If only a single tunnel is needed, callCreateTunnel.Builder.withBindTls(BindTls)
withBindTls.TRUE
and a reference to thehttps
tunnel will be returned.Get Active Tunnels
It can be useful to ask thengrok
client what tunnels are currently open. This can be accomplished with thegetTunnels()
method, which returns a list ofTunnel
objects.[<Tunnel: "http://<public_sub>.ngrok.io" -> "http://localhost:80">] final List<Tunnel> tunnels = ngrokClient.getTunnels();
Close a Tunnel
All open tunnels will automatically be closed when the Java process terminates, but we can also close them manually withdisconnect(String)
.// The Tunnel returned from methods like connect(), getTunnels(), etc. contains the public URL ngrokClient.disconnect(publicUrl);
Integration Examples
java-ngrok
is useful in any number of integrations, for instance to test locally without having to deploy or configure. Here are some common usage examples.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
NgrokClient.Builder
Builder for aNgrokClient
, see docs for that class for example usage.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description Tunnel
connect()
Tunnel
connect(CreateTunnel createTunnel)
Establish a newngrok
tunnel for the tunnel definition, returning an object representing the connected tunnel.void
disconnect(java.lang.String publicUrl)
Disconnect thengrok
tunnel for the given URL, if open.HttpClient
getHttpClient()
Get the class used to make HTTP requests tongrok
's APIs.JavaNgrokConfig
getJavaNgrokConfig()
Get thejava-ngrok
to use when interacting with thengrok
binary.NgrokProcess
getNgrokProcess()
Get the class used to manage thengrok
binary.java.util.List<Tunnel>
getTunnels()
Get a list of activengrok
tunnels.Version
getVersion()
Get thengrok
andjava-ngrok
version.void
kill()
Terminate thengrok
processes, if running.void
refreshMetrics(Tunnel tunnel)
Get the latest metrics for the givenTunnel
and update itsmetrics
attribute.void
setAuthToken(java.lang.String authToken)
Set thengrok
auth token in the config file, enabling authenticated features (for instance, more concurrent tunnels, custom subdomains, etc.).void
update()
Updatengrok
, if an update is available.
-
-
-
Method Detail
-
connect
public Tunnel connect(CreateTunnel createTunnel)
Establish a newngrok
tunnel for the tunnel definition, returning an object representing the connected tunnel.If
ngrok
is not running, calling this method will first start a process withJavaNgrokConfig
.Note:
ngrok
's default behavior forhttp
when no additional properties are passed is to open two tunnels, onehttp
and onehttps
. This method will return a reference to thehttp
tunnel in this case. If only a single tunnel is needed, callCreateTunnel.Builder.withBindTls(BindTls)
withBindTls.TRUE
and a reference to thehttps
tunnel will be returned.- Parameters:
createTunnel
- The tunnel definition.- Returns:
- The created Tunnel.
-
connect
public Tunnel connect()
-
disconnect
public void disconnect(java.lang.String publicUrl)
Disconnect thengrok
tunnel for the given URL, if open.- Parameters:
publicUrl
- The public URL of the tunnel to disconnect.
-
getTunnels
public java.util.List<Tunnel> getTunnels()
Get a list of activengrok
tunnels.If
ngrok
is not running, calling this method will first start a process withJavaNgrokConfig
.- Returns:
- The active
ngrok
tunnels.
-
refreshMetrics
public void refreshMetrics(Tunnel tunnel)
Get the latest metrics for the givenTunnel
and update itsmetrics
attribute.- Parameters:
tunnel
- The Tunnel to update.
-
kill
public void kill()
Terminate thengrok
processes, if running. This method will not block, it will just issue a kill request.
-
setAuthToken
public void setAuthToken(java.lang.String authToken)
Set thengrok
auth token in the config file, enabling authenticated features (for instance, more concurrent tunnels, custom subdomains, etc.).- Parameters:
authToken
- The auth token.
-
update
public void update()
Updatengrok
, if an update is available.
-
getVersion
public Version getVersion()
Get thengrok
andjava-ngrok
version.- Returns:
- The versions.
-
getJavaNgrokConfig
public JavaNgrokConfig getJavaNgrokConfig()
Get thejava-ngrok
to use when interacting with thengrok
binary.
-
getNgrokProcess
public NgrokProcess getNgrokProcess()
Get the class used to manage thengrok
binary.
-
getHttpClient
public HttpClient getHttpClient()
Get the class used to make HTTP requests tongrok
's APIs.
-
-