Package com.github.alexdlaird.ngrok

Class NgrokClient

  • public class NgrokClient
extends java.lang.Object
    A client for interacting with ngrok, its binary, and its APIs. Can be configured with JavaNgrokConfig.

    Open a Tunnel

    To open a tunnel, use the NgrokClient.connect() method, which returns a Tunnel, and this returned object has a reference to the public URL generated by ngrok in its Tunnel.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);

    The connect() method can also take a CreateTunnel (which can be built through its Builder) that allows us to pass additional properties that are supported by ngrok.

    Note: ngrok's default behavior for http when no additional properties are passed is to open two tunnels, one http and one https. This method will return a reference to the http tunnel in this case. If only a single tunnel is needed, call CreateTunnel.Builder.withBindTls(BindTls) with BindTls.TRUE and a reference to the https tunnel will be returned.

    Get Active Tunnels

    It can be useful to ask the ngrok client what tunnels are currently open. This can be accomplished with the getTunnels() method, which returns a list of Tunnel 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 with disconnect(String). 

     // The Tunnel returned from methods like connect(), getTunnels(), etc. contains the public URL
 ngrokClient.disconnect(publicUrl);

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      Tunnel connect()
      See connect(CreateTunnel).
      Tunnel connect​(CreateTunnel createTunnel)
      Establish a new ngrok tunnel for the tunnel definition, returning an object representing the connected tunnel.
      void disconnect​(java.lang.String publicUrl)
      Disconnect the ngrok tunnel for the given URL, if open.
      HttpClient getHttpClient()
      Get the class used to make HTTP requests to ngrok's APIs.
      JavaNgrokConfig getJavaNgrokConfig()
      Get the java-ngrok to use when interacting with the ngrok binary.
      NgrokProcess getNgrokProcess()
      Get the class used to manage the ngrok binary.
      java.util.List<Tunnel> getTunnels()
      Get a list of active ngrok tunnels.
      Version getVersion()
      Get the ngrok and java-ngrok version.
      void kill()
      Terminate the ngrok processes, if running.
      void setAuthToken​(java.lang.String authToken)
      Set the ngrok auth token in the config file, enabling authenticated features (for instance, more concurrent tunnels, custom subdomains, etc.).
      void update()
      Update ngrok, if an update is available.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Method Detail

      • connect

        public Tunnel connect​(CreateTunnel createTunnel)
        Establish a new ngrok 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 with JavaNgrokConfig.

        Note: ngrok's default behavior for http when no additional properties are passed is to open two tunnels, one http and one https. This method will return a reference to the http tunnel in this case. If only a single tunnel is needed, call CreateTunnel.Builder.withBindTls(BindTls) with BindTls.TRUE and a reference to the https tunnel will be returned.

        Parameters:
        createTunnel - The tunnel definition.
        Returns:
        The created Tunnel.

      • disconnect

        public void disconnect​(java.lang.String publicUrl)
        Disconnect the ngrok 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 active ngrok tunnels.

        If ngrok is not running, calling this method will first start a process with JavaNgrokConfig.

        Returns:
        The active ngrok tunnels.

      • kill

        public void kill()
        Terminate the ngrok processes, if running. This method will not block, it will just issue a kill request.

      • setAuthToken

        public void setAuthToken​(java.lang.String authToken)
        Set the ngrok 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()
        Update ngrok, if an update is available.

      • getVersion

        public Version getVersion()
        Get the ngrok and java-ngrok version.
        Returns:
        The versions.

      • getJavaNgrokConfig

        public JavaNgrokConfig getJavaNgrokConfig()
        Get the java-ngrok to use when interacting with the ngrok binary.

      • getNgrokProcess

        public NgrokProcess getNgrokProcess()
        Get the class used to manage the ngrok binary.

      • getHttpClient

        public HttpClient getHttpClient()
        Get the class used to make HTTP requests to ngrok's APIs.