ngrok Clojure wrapper

This is a small clojure library and its accompanying boot task to use ngrok.

It can open a ngrok tunnel, and it will expose the public url of this tunnel as a JVM property. You can access it like this (System/getProperty "ngrok-tunnel-url"), or even better, if you use the aero config library, you can read it from your configuration file using the reader #prop ngrok-tunnel-url.

You must provide a ngrok binary available on your PATH, or otherwise available on you filesystem (see the :bin-path option for more informations).

WARNING

This is alpha software! The API will break (and hopefully improve) in future versions. Upgrade with caution.

This first release is REALLY NOISY in the stdout, I have yet to figure out how to do logging in a way that is manageable by the users of this lib.

Also, for now, calling start will block the user thread, but it would be better provide more options to the user (like the http-kit client does maybe). Furthermore, There is a dependency on core.async, we should get rid it of for a wrapper this thin.

Basic usage

Require it in one of your namespaces (require '[com.chpill.ngrok :as ngrok]).

Open a http tunnel (def stop-ngrok-process (ngrok/start {:port 80 :protocol "http" :region "eu"}))

Note that the start returns a function that stops the ngrok process.

Option list:

• :port (default 80)
• :protocol (default "http")
• :region (default "eu")
• :bin-path an optional path to you ngrok binary if you don't have it on your PATH (or do not want to use the one on your path)

A convenience function is provided if you want the process to be stopped automatically on JVM shutdown start-long-running.

A boot task is provided if you want to use start-long-running along with your other boot tasks:

(require '[com.chpill.ngrok.boot :refer [boot-ngrok]])

(deftask dev []
  (comp ...
        (boot-ngrok)
        ...))

Why?

Ngrok is a wonderful utility to test integration with external services locally on your development environment. In particular, This wrapper was conceived while integrating trello webhooks with a clojure app, and greatly simplified the development workflow.

How?

This wrapper starts a ngrok process outside of the JVM, then communicate with its HTTP API to open the requested tunnel.

License: BSD

Copyright © 2016 Etienne Spillemaeker. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.