com.github.alexdlaird.ngrok.conf.JavaNgrokConfig Maven / Gradle / Ivy

Go to download

/*
 * Copyright (c) 2023 Alex Laird
 *
 * Permission is hereby granted, free of charge, to any person obtaining
 * a copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, sublicense, and/or sell copies of the Software, and to
 * permit persons to whom the Software is furnished to do so, subject to
 * the following conditions:
 *
 * The above copyright notice and this permission notice shall be
 * included in all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
 * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
 * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */

package com.github.alexdlaird.ngrok.conf;

import com.github.alexdlaird.ngrok.installer.NgrokInstaller;
import com.github.alexdlaird.ngrok.installer.NgrokVersion;
import com.github.alexdlaird.ngrok.process.NgrokLog;
import com.github.alexdlaird.ngrok.protocol.CreateTunnel;
import com.github.alexdlaird.ngrok.protocol.Region;

import java.nio.file.Path;
import java.util.function.Function;

import static java.util.Objects.isNull;

/**
 * An object for managing java-ngrok's configuration to interact the ngrok binary.
 *
 * Basic Usage
 *  * final Function<NgrokLog, Void> logEventCallback = ngrokLog -> {
 *     System.out.println(ngrokLog.getLine());
 *     return null;
 * };
 * final JavaNgrokConfig javaNgrokConfig = new JavaNgrokConfig.Builder()
 *         .withAuthToken("<NGROK_AUTH_TOKEN>")
 *         .withRegion(Region.AU)
 *         .withLogEventCallback(logEventCallback)
 *         .withMaxLogs(10);
 *
 * final NgrokClient ngrokClient = new NgrokClient.Builder()
 *         .withJavaNgrokConfig(javaNgrokConfig)
 *         .build();
 * 
 * ngrok Version Compatibility
 * java-ngrok is compatible with ngrok v2 and v3, but by default it will install v3. To
 * install v2 instead, set the version with {@link JavaNgrokConfig.Builder#withNgrokVersion(NgrokVersion)}
 * and {@link CreateTunnel.Builder#withNgrokVersion(NgrokVersion)}.
 */
public class JavaNgrokConfig {

    private final Path ngrokPath;
    private final Path configPath;
    private final String authToken;
    private final Region region;
    private final boolean keepMonitoring;
    private final int maxLogs;
    private final Function logEventCallback;
    private final int startupTimeout;
    private final NgrokVersion ngrokVersion;
    private final String apiKey;

    private JavaNgrokConfig(final Builder builder) {
        this.ngrokPath = builder.ngrokPath;
        this.configPath = builder.configPath;
        this.authToken = builder.authToken;
        this.region = builder.region;
        this.keepMonitoring = builder.keepMonitoring;
        this.maxLogs = builder.maxLogs;
        this.logEventCallback = builder.logEventCallback;
        this.startupTimeout = builder.startupTimeout;
        this.ngrokVersion = builder.ngrokVersion;
        this.apiKey = builder.apiKey;
    }

    /**
     * Get the path to the ngrok binary.
     */
    public Path getNgrokPath() {
        return ngrokPath;
    }

    /**
     * Get the path to the ngrok config file.
     */
    public Path getConfigPath() {
        return configPath;
    }

    /**
     * Get the ngrok authtoken that will be passed to commands.
     */
    public String getAuthToken() {
        return authToken;
    }

    /**
     * Get the region in which ngrok will start.
     */
    public Region getRegion() {
        return region;
    }

    /**
     * Get whether the ngrok process will continue to be monitored after it finishes starting up.
     */
    public boolean isKeepMonitoring() {
        return keepMonitoring;
    }

    /**
     * Get the maximum number of ngrok logs to retain in the monitoring thread.
     */
    public int getMaxLogs() {
        return maxLogs;
    }

    /**
     * Get the log event callback that will be invoked each time ngrok emits a log.
     */
    public Function getLogEventCallback() {
        return logEventCallback;
    }

    /**
     * Get the startup time before ngrok times out on boot.
     */
    public int getStartupTime() {
        return startupTimeout;
    }

    /**
     * Get the major ngrok version to be used.
     */
    public NgrokVersion getNgrokVersion() {
        return ngrokVersion;
    }

    /**
     * A ngrok API key.
     */
    public String getApiKey() {
        return apiKey;
    }

    /**
     * Builder for a {@link JavaNgrokConfig}, see docs for that class for example usage.
     */
    public static class Builder {

        private Path ngrokPath;
        private Path configPath;
        private String authToken;
        private Region region;
        private boolean keepMonitoring = true;
        private int maxLogs = 100;
        private Function logEventCallback;
        private int startupTimeout = 15;
        private NgrokVersion ngrokVersion = NgrokVersion.V3;
        private String apiKey;

        public Builder() {
        }

        /**
         * Copy a {@link JavaNgrokConfig} in to a new Builder.
         *
         * @param javaNgrokConfig The JavaNgrokConfig to copy.
         */
        public Builder(final JavaNgrokConfig javaNgrokConfig) {
            this.ngrokPath = javaNgrokConfig.ngrokPath;
            this.configPath = javaNgrokConfig.configPath;
            this.authToken = javaNgrokConfig.authToken;
            this.region = javaNgrokConfig.region;
            this.keepMonitoring = javaNgrokConfig.keepMonitoring;
            this.maxLogs = javaNgrokConfig.maxLogs;
            this.logEventCallback = javaNgrokConfig.logEventCallback;
            this.startupTimeout = javaNgrokConfig.startupTimeout;
            this.ngrokVersion = javaNgrokConfig.ngrokVersion;
            this.apiKey = javaNgrokConfig.apiKey;
        }

        /**
         * The path to the ngrok binary, defaults to ~/.ngrok2/ngrok.
         */
        public Builder withNgrokPath(final Path ngrokPath) {
            this.ngrokPath = ngrokPath;
            return this;
        }

        /**
         * The path to the ngrok config file, defaults to ~/.ngrok2/ngrok.yml.
         */
        public Builder withConfigPath(final Path configPath) {
            this.configPath = configPath;
            return this;
        }

        /**
         * A ngrok authtoken to pass to commands (overrides what is in the config).
         */
        public Builder withAuthToken(final String authToken) {
            this.authToken = authToken;
            return this;
        }

        /**
         * The region in which ngrok should start.
         *


         */
        public Builder withRegion(final Region region) {
            this.region = region;
            return this;
        }

        /**
         * Don't keep monitoring ngrok (for logs, etc.) after startup is complete.
         */
        public Builder withoutMonitoring() {
            this.keepMonitoring = false;
            return this;
        }

        /**
         * The maximum number of ngrok logs to retain in the monitoring thread.
         */
        public Builder withMaxLogs(final int maxLogs) {
            if (maxLogs < 1) {
                throw new IllegalArgumentException("\"maxLogs\" must be greater than 0.");
            }

            this.maxLogs = maxLogs;
            return this;
        }

        /**
         * A callback that will be invoked each time ngrok emits a log. {@link #keepMonitoring} must be
         * set to true or the function will stop being called after ngrok finishes starting.
         */
        public Builder withLogEventCallback(final Function logEventCallback) {
            this.logEventCallback = logEventCallback;
            return this;
        }

        /**
         * The max number of seconds to wait for ngrok to start before timing out.
         */
        public Builder withStartupTimeout(final int startupTimeout) {
            if (startupTimeout < 1) {
                throw new IllegalArgumentException("\"startupTimeout\" must be greater than 0.");
            }

            this.startupTimeout = startupTimeout;
            return this;
        }

        /**
         * The major version of ngrok to be used.
         */
        public Builder withNgrokVersion(final NgrokVersion ngrokVersion) {
            this.ngrokVersion = ngrokVersion;
            return this;
        }

        /**
         * A ngrok API key.
         */
        public Builder withApiKey(final String apiKey) {
            this.apiKey = apiKey;
            return this;
        }

        public JavaNgrokConfig build() {
            if (isNull(ngrokPath)) {
                ngrokPath = NgrokInstaller.DEFAULT_NGROK_PATH;
            }
            if (isNull(configPath)) {
                configPath = NgrokInstaller.DEFAULT_CONFIG_PATH;
            }

            return new JavaNgrokConfig(this);
        }
    }
}