v1.4.0

don't emit ETIMEDOUT-errors

.travis.yml

@@ -1,4 +1,3 @@
 language: node_js
 node_js:
-    - 0.8
-    - 0.9
+    - "0.10"

History.md

@@ -0,0 +1,19 @@
+# 1.4.0 (2014-08-31)
+
+* don't emit errors for ETIMEDOUT
+
+# 1.2.0 / 2014-04-28
+
+* return `client` from `localtunnel` API instantiation
+
+# 1.1.0 / 2014-02-24
+
+* add a host header transform to change the 'Host' header in requests
+
+# 1.0.0 / 2014-02-14
+
+* default to localltunnel.me for host
+* remove exported `connect` method (just export one function that does the same thing)
+* change localtunnel signature to (port, opt, fn)
+
+# 0.2.2 / 2014-01-09

README.md

@@ -1,4 +1,4 @@
-# localtunnel #
+# localtunnel [![Build Status](https://travis-ci.org/defunctzombie/localtunnel.png?branch=master)](https://travis-ci.org/defunctzombie/localtunnel) #
 
 localtunnel exposes your localhost to the world for easy testing and sharing! No need to mess with DNS or deploy just to have others test out your changes.
 
@@ -14,7 +14,7 @@ This will install the localtunnel module globally and add the 'lt' client cli to
 
 ## use ##
 
-Super Easy! Assuming your local server is running on port 8000, just use the ```lt``` command to start the tunnel.
+Assuming your local server is running on port 8000, just use the ```lt``` command to start the tunnel.
 
 ```
 lt --port 8000
@@ -24,31 +24,53 @@ Thats it! It will connect to the tunnel server, setup the tunnel, and tell you w
 
 You can restart your local server all you want, ```lt``` is smart enough to detect this and reconnect once it is back.
 
+### arguments
+
+Below are some common arguments. See `lt --help` for additional arguments
+
+* `--subdomain` request a named subdomain on the localtunnel server (default is random characters)
+* `--local-host` proxy to a hostname other than localhost
+
 ## API ##
 
 The localtunnel client is also usable through an API (for test integration, automation, etc)
 
+### localtunnel(port [,opts], fn)
+
+Creates a new localtunnel to the specified local `port`. `fn` will be called once you have been assigned a public localtunnel url. `opts` can be used to request a specific `subdomain`.
+
 ```javascript
 var localtunnel = require('localtunnel');
 
-var client = localtunnel.connect({
-    // the localtunnel server
-    host: 'http://localtunnel.me',
-    // your local application port
-    port: 12345
-});
+localtunnel(port, function(err, tunnel) {
+    if (err) ...
 
-// when your are assigned a url
-client.on('url', function(url) {
-    // you can now make http requests to the url
-    // they will be proxied to your local server on port [12345]
-});
-
-client.on('error', function(err) {
-    // uh oh!
+    // the assigned public url for your tunnel
+    // i.e. https://abcdefgjhij.localtunnel.me
+    tunnel.url;
 });
 ```
 
+### opts
+
+* `subdomain` A *string* value requesting a specific subdomain on the proxy server. **Note** You may not actually receive this name depending on availablily.
+* `local_host` Proxy to this hostname instead of `localhost`. This will also cause the `Host` header to be re-written to this value in proxied requests.
+
+### Tunnel
+
+The `tunnel` instance returned to your callback emits the following events
+
+|event|args|description|
+|----|----|----|
+|error|err|fires when an error happens on the tunnel|
+|close||fires when the tunnel has closed|
+
+The `tunnel instance has the following methods
+
+|method|args|description|
+|----|----|----|
+|close||close the tunnel|
+
 ## other clients ##
 
 Clients in other languages
@@ -57,7 +79,7 @@ Clients in other languages
 
 ## server ##
 
-See shtylman/localtunnel-server for details on the server that powers localtunnel.
+See defunctzombie/localtunnel-server for details on the server that powers localtunnel.
 
 ## License ##
 MIT

bin/client

@@ -3,7 +3,6 @@ var lt_client = require('../client');
 
 var argv = require('optimist')
     .usage('Usage: $0 --port [num]')
-    .demand(['port'])
     .options('host', {
         default: 'http://localtunnel.me',
         describe: 'upstream server providing forwarding'
@@ -12,28 +11,42 @@ var argv = require('optimist')
         describe: 'request this subdomain'
     })
     .options('local-host', {
-        describe: 'tunnel traffic to this host instead of localhost'
+        describe: 'tunnel traffic to this host instead of localhost, override Host header to this host'
+    })
+    .options('version', {
+        describe: 'print version and exit'
     })
-    .default('local-host', 'localhost')
     .describe('port', 'internal http server port')
     .argv;
 
+if (argv.version) {
+    console.log(require('../package.json').version);
+    process.exit(0);
+}
+
+if (argv.port == null) {
+    require('optimist').showHelp();
+    console.error('Missing required arguments: port');
+    process.exit(1);
+}
+
 var opt = {
     host: argv.host,
     port: argv.port,
     local_host: argv['local-host'],
     subdomain: argv.subdomain,
-}
+};
 
-var client = lt_client.connect(opt);
+lt_client(opt.port, opt, function(err, tunnel) {
+    if (err) {
+        throw err;
+    }
 
-// only emitted when the url changes
-client.on('url', function(url) {
-    console.log('your url is: %s', url);
-});
+    console.log('your url is: %s', tunnel.url);
 
-client.on('error', function(err) {
-    console.error(err);
+    tunnel.on('error', function(err) {
+        throw err;
+    });
 });
 
 // vim: ft=javascript

client.js

@@ -5,6 +5,44 @@ var EventEmitter = require('events').EventEmitter;
 var request = require('request');
 var debug = require('debug')('localtunnel:client');
 
+var stream = require('stream');
+var util = require('util');
+
+var Transform = stream.Transform;
+
+var HeaderHostTransformer = function(opts) {
+    if (!(this instanceof HeaderHostTransformer)) {
+        return new HeaderHostTransformer(opts);
+    }
+
+    opts = opts || {}
+    Transform.call(this, opts);
+
+    var self = this;
+    self.host = opts.host || 'localhost';
+    self.replaced = false;
+}
+util.inherits(HeaderHostTransformer, Transform);
+
+HeaderHostTransformer.prototype._transform = function (chunk, enc, cb) {
+    var self = this;
+    chunk = chunk.toString();
+
+    // after replacing the first instance of the Host header
+    // we just become a regular passthrough
+    if (!self.replaced) {
+        self.push(chunk.replace(/(\r\nHost: )\S+/, function(match, $1) {
+            self.replaced = true;
+            return $1 + self.host;
+        }));
+    }
+    else {
+        self.push(chunk);
+    }
+
+    cb();
+};
+
 // manages groups of tunnels
 var TunnelCluster = function(opt) {
     if (!(this instanceof TunnelCluster)) {
@@ -28,7 +66,7 @@ TunnelCluster.prototype.open = function() {
     var remote_host = opt.remote_host;
     var remote_port = opt.remote_port;
 
-    var local_host = opt.local_host;
+    var local_host = opt.local_host || 'localhost';
     var local_port = opt.local_port;
 
     debug('establishing tunnel %s:%s <> %s:%s', local_host, local_port, remote_host, remote_port);
@@ -45,7 +83,7 @@ TunnelCluster.prototype.open = function() {
         if (err.code === 'ECONNREFUSED') {
             self.emit('error', new Error('connection refused: ' + remote_host + ':' + remote_port + ' (check your firewall settings)'));
         }
-        else {
+        else if (err.code !== 'ETIMEDOUT') {
             self.emit('error', err);
         }
 
@@ -55,13 +93,13 @@ TunnelCluster.prototype.open = function() {
     });
 
     function conn_local() {
-        debug('connecting locally to %s:%d', local_host, local_port);
-
         if (remote.destroyed) {
+            debug('remote destroyed');
             self.emit('dead');
             return;
         }
 
+        debug('connecting locally to %s:%d', local_host, local_port);
         remote.pause();
 
         // connection to local http server
@@ -71,19 +109,24 @@ TunnelCluster.prototype.open = function() {
         });
 
         function remote_close() {
+            debug('remote close');
             self.emit('dead');
             local.end();
         };
 
         remote.once('close', remote_close);
 
-        local.on('error', function(err) {
+        // TODO some languages have single threaded servers which makes opening up
+        // multiple local connections impossible. We need a smarter way to scale
+        // and adjust for such instances to avoid beating on the door of the server
+        local.once('error', function(err) {
+            debug('local error %s', err.message);
             local.end();
 
             remote.removeListener('close', remote_close);
 
             if (err.code !== 'ECONNREFUSED') {
-                return local.emit('error', err);
+                return remote.end();
             }
 
             // retrying connection to local server
@@ -93,7 +136,17 @@ TunnelCluster.prototype.open = function() {
         local.once('connect', function() {
             debug('connected locally');
             remote.resume();
-            remote.pipe(local).pipe(remote);
+
+            var stream = remote;
+
+            // if user requested specific local host
+            // then we use host header transform to replace the host header
+            if (opt.local_host) {
+                debug('transform Host header to %s', opt.local_host);
+                stream = remote.pipe(HeaderHostTransformer({ host: opt.local_host }));
+            }
+
+            stream.pipe(local).pipe(remote);
 
             // when local closes, also get a new remote
             local.once('close', function(had_error) {
@@ -105,8 +158,8 @@ TunnelCluster.prototype.open = function() {
     // tunnel is considered open when remote connects
     remote.once('connect', function() {
         self.emit('open', remote);
+        conn_local();
     });
-    remote.once('connect', conn_local);
 };
 
 var Tunnel = function(opt) {
@@ -116,7 +169,9 @@ var Tunnel = function(opt) {
 
     var self = this;
     self._closed = false;
-    self._opt = opt;
+    self._opt = opt || {};
+
+    self._opt.host = self._opt.host || 'https://localtunnel.me';
 };
 
 Tunnel.prototype.__proto__ = EventEmitter.prototype;
@@ -151,6 +206,11 @@ Tunnel.prototype._init = function(cb) {
                 return setTimeout(get_url, 1000);
             }
 
+            if (res.statusCode !== 200) {
+                var err = new Error((body && body.message) || 'localtunnel server returned an error, please try again');
+                return cb(err);
+            }
+
             var port = body.port;
             var host = upstream.hostname;
 
@@ -171,7 +231,7 @@ Tunnel.prototype._establish = function(info) {
     var self = this;
     var opt = self._opt;
 
-    info.local_host = opt.local_host || 'localhost';
+    info.local_host = opt.local_host;
     info.local_port = opt.port;
 
     var tunnels = self.tunnel_cluster = TunnelCluster(info);
@@ -220,15 +280,17 @@ Tunnel.prototype._establish = function(info) {
     }
 };
 
-Tunnel.prototype.open = function() {
+Tunnel.prototype.open = function(cb) {
     var self = this;
 
     self._init(function(err, info) {
         if (err) {
-            return self.emit('error', err);
+            return cb(err);
         }
 
+        self.url = info.url;
         self._establish(info);
+        cb();
     });
 };
 
@@ -240,8 +302,22 @@ Tunnel.prototype.close = function() {
     self.emit('close');
 };
 
-module.exports.connect = function(opt) {
+module.exports = function localtunnel(port, opt, fn) {
+    if (typeof opt === 'function') {
+        fn = opt;
+        opt = {};
+    }
+
+    opt = opt || {};
+    opt.port = port;
+
     var client = Tunnel(opt);
-    client.open();
+    client.open(function(err) {
+        if (err) {
+            return fn(err);
+        }
+
+        fn(null, client);
+    });
     return client;
 };

package.json

@@ -2,7 +2,7 @@
   "author": "Roman Shtylman <shtylman@gmail.com>",
   "name": "localtunnel",
   "description": "expose localhost to the world",
-  "version": "0.2.2",
+  "version": "1.4.0",
   "repository": {
     "type": "git",
     "url": "git://github.com/shtylman/localtunnel.git"
@@ -12,9 +12,14 @@
     "optimist": "0.3.4",
     "debug": "0.7.4"
   },
-  "devDependencies": {},
+  "devDependencies": {
+    "mocha": "~1.17.0"
+  },
+  "scripts": {
+    "test": "mocha --ui qunit --reporter list --timeout 10000 -- test/index.js"
+  },
   "bin": {
     "lt": "./bin/client"
   },
   "main": "./client.js"
-}
+}

test/index.js

@@ -0,0 +1,188 @@
+var http = require('http');
+var https = require('https');
+var url = require('url');
+var assert = require('assert');
+
+var localtunnel = require('../');
+
+test('setup local http server', function(done) {
+    var server = http.createServer();
+    server.on('request', function(req, res) {
+        res.write(req.headers.host);
+        res.end();
+    });
+    server.listen(function() {
+        var port = server.address().port;
+
+        test._fake_port = port;
+        console.log('local http on:', port);
+        done();
+    });
+});
+
+test('setup localtunnel client', function(done) {
+    localtunnel(test._fake_port, function(err, tunnel) {
+        assert.ifError(err);
+        assert.ok(new RegExp('^https:\/\/.*localtunnel.me' + '$').test(tunnel.url));
+        test._fake_url = tunnel.url;
+        done();
+    });
+});
+
+test('query localtunnel server w/ ident', function(done) {
+    var uri = test._fake_url;
+    var parsed = url.parse(uri);
+
+    var opt = {
+        host: parsed.host,
+        port: 443,
+        headers: {
+            host: parsed.hostname
+        },
+        path: '/'
+    };
+
+    var req = https.request(opt, function(res) {
+        res.setEncoding('utf8');
+        var body = '';
+
+        res.on('data', function(chunk) {
+            body += chunk;
+        });
+
+        res.on('end', function() {
+            assert(/.*[.]localtunnel[.]me/.test(body), body);
+            done();
+        });
+    });
+
+    req.end();
+});
+
+test('request specific domain', function(done) {
+    localtunnel(test._fake_port, { subdomain: 'abcd' }, function(err, tunnel) {
+        assert.ifError(err);
+        assert.ok(new RegExp('^https:\/\/abcd.localtunnel.me' + '$').test(tunnel.url));
+        tunnel.close();
+        done();
+    });
+});
+
+suite('--local-host localhost');
+
+test('setup localtunnel client', function(done) {
+    var opt = {
+        local_host: 'localhost'
+    };
+    localtunnel(test._fake_port, opt, function(err, tunnel) {
+        assert.ifError(err);
+        assert.ok(new RegExp('^https:\/\/.*localtunnel.me' + '$').test(tunnel.url));
+        test._fake_url = tunnel.url;
+        done();
+    });
+});
+
+test('override Host header with local-host', function(done) {
+    var uri = test._fake_url;
+    var parsed = url.parse(uri);
+
+    var opt = {
+        host: parsed.host,
+        port: 443,
+        headers: {
+            host: parsed.hostname
+        },
+        path: '/'
+    };
+
+    var req = https.request(opt, function(res) {
+        res.setEncoding('utf8');
+        var body = '';
+
+        res.on('data', function(chunk) {
+            body += chunk;
+        });
+
+        res.on('end', function() {
+            assert.equal(body, 'localhost');
+            done();
+        });
+    });
+
+    req.end();
+});
+
+suite('--local-host 127.0.0.1');
+
+test('setup localtunnel client', function(done) {
+    var opt = {
+        local_host: '127.0.0.1'
+    };
+    localtunnel(test._fake_port, opt, function(err, tunnel) {
+        assert.ifError(err);
+        assert.ok(new RegExp('^https:\/\/.*localtunnel.me' + '$').test(tunnel.url));
+        test._fake_url = tunnel.url;
+        done();
+    });
+});
+
+test('override Host header with local-host', function(done) {
+    var uri = test._fake_url;
+    var parsed = url.parse(uri);
+
+    var opt = {
+        host: parsed.host,
+        port: 443,
+        headers: {
+            host: parsed.hostname
+        },
+        path: '/'
+    };
+
+    var req = https.request(opt, function(res) {
+        res.setEncoding('utf8');
+        var body = '';
+
+        res.on('data', function(chunk) {
+            body += chunk;
+        });
+
+        res.on('end', function() {
+            assert.equal(body, '127.0.0.1');
+            done();
+        });
+    });
+
+    req.end();
+});
+
+test('send chunked request', function(done) {
+    var uri = test._fake_url;
+    var parsed = url.parse(uri);
+
+    var opt = {
+        host: parsed.host,
+        port: 443,
+        headers: {
+            host: parsed.hostname,
+            'Transfer-Encoding': 'chunked'
+        },
+        path: '/'
+    };
+
+    var req = https.request(opt, function(res) {
+        res.setEncoding('utf8');
+        var body = '';
+
+        res.on('data', function(chunk) {
+            body += chunk;
+        });
+
+        res.on('end', function() {
+            assert.equal(body, '127.0.0.1');
+            done();
+        });
+    });
+
+    req.end(require('crypto').randomBytes(1024 * 8).toString('base64'));
+});