0.0.7 • Published 4 years ago
localxpose-test v0.0.7
Nodejs Client Library
The official nodejs binding for LocalXpose
Prerequisites
You can use this library as a guest account or by applying your access token, If you don't have an account you can create one, sign up for a new account or login and get your access token.
Installation
npm install localxpose
# or
yarn add localxpose
Usage
1. Creating a LocalXpose client
Passing in an access token or leave it empty for a guest limited account
const LocalXpose = require('localxpose')
const client = new LocalXpose('YOUR_ACCESS_TOKEN')
// or using an access token stored in an environment variable as LOCALXPOSE_ACCESS_TOKEN
const client = new LocalXpose()
2. Start your tunnel
http tunnel
(async function(){
let httpTunnel = await client.http()
// or
let httpTunnel = await client.http({
region: 'us', // us, ap or eu (default: us)
to: '127.0.0.1:9090', // address to forward to (default: 127.0.0.1:8080)
subdomain: 'hello-world', // tunnel subdomain (default: random)
reservedDomain: 'my.custom-domain.com', // reserved domain
hostheader: 'myapp.localhost.com', // rewrite host header
basicAuth: 'user:pass', // protect the tunnel with username and password
eventCallback: callback // tunnel events callback
})
})()
// or
client.http()
.then((tunnel) => console.log(`I am available on ${tunnel.addr}`))
.catch((err) => console.log(err))
tls tunnel
(async function(){
let tlsTunnel = await client.tls()
// or
let tlsTunnel = await client.tls({
region: 'us', // us, ap or eu (default: us)
to: '127.0.0.1:9090', // address to forward to (default: 127.0.0.1:8080)
subdomain: 'hello-world', // tunnel subdomain (default: random)
reservedDomain: 'my.custom-domain.com', // reserved domain
crt: '/path/to/cert.pem', // if you want localxpose client to terminate the tls connection
key: '/path/to/key.pem', // if you want localxpose client to terminate the tls connection
eventCallback: callback // tunnel events callback
})
})()
// or
client.tls()
.then((tunnel) => console.log(`I am available on ${tunnel.addr}`))
.catch((err) => console.log(err))
tcp tunnel
(async function(){
let tcpTunnel = await client.tcp()
// or
let tcpTunnel = await client.tcp({
region: 'us', // us, ap or eu (default: us)
to: '127.0.0.1:9090', // address to forward to (default: 127.0.0.1:8080)
port: 8181, // choose a public port for your tunnel (default: random)
reservedEndpoint: 'us-1.loclx.io:4444', // reserved endpoint
eventCallback: callback // tunnel events callback
})
})()
// or
client.tcp()
.then((tunnel) => console.log(`I am available on ${tunnel.addr}`))
.catch((err) => console.log(err))
udp tunnel
(async function(){
let udpTunnel = await client.udp()
// or
let udpTunnel = await client.udp({
region: 'us', // us, ap or eu (default: us)
to: '127.0.0.1:9090', // address to forward to (default: 127.0.0.1:8080)
port: 8181, // choose a public port for your tunnel (default: random)
reservedEndpoint: 'us-1.loclx.io:4444', // reserved endpoint
eventCallback: callback // tunnel events callback
})
})()
// or
client.udp()
.then((tunnel) => console.log(`I am available on ${tunnel.addr}`))
.catch((err) => console.log(err))
file server tunnel
(async function(){
let fileSrvTunnel = await client.fileServer({path: '/path/to/directory'})
// or
let fileSrvTunnel = await client.fileServer({
region: 'us', // us, ap or eu (default: us)
subdomain: 'fileserver', // tunnel subdomain (default: random)
reservedDomain: 'reserved-fileserver.loclx.io', // reserved domain
basicAuth: 'user:pass', // protect the tunnel with username and password
path: '/path/to/directory', // path to be served
eventCallback: callback // tunnel events callback
})
})()
// or
client.fileServer({path: '/path/to/dir'})
.then((tunnel) => console.log(`I am available on ${tunnel.addr}`))
.catch((err) => console.log(err))
close the tunnel
let httpTunnel = await client.http()
await httpTunnel.close()
close all the tunnels and kill LocalXpose process
client.kill()
API
LocalXpose Class
new LocalXpose(accessToken) - Initialization
accessToken
- Required: No (you can use access token stored in
LOCALXPOSE_ACCESS_TOKEN
environment variable) - A passed in accessToken will take precedence over an environment variable
- Required: No (you can use access token stored in
Methods
Notes:
- http(options) - create http tunnel, returns
HlsTunnel
objectregion
- can be 'us', 'ap' or 'eu' (default: 'us')to
- address to forward to (default: 127.0.0.1:8080)subdomain
- tunnel subdomain (default: random)reservedDomain
- reserved domain either custom domain or subdomainhostheader
- rewrite host header with a custom onebasicAuth
- protect the tunnel with basic authentication in the form ofuser:pass
eventCallback
- tunnel events callback, see below- NOTE: if
reservedDomain
is supplied,subdomain
andregion
are neglected
- fileServer(options) - create a file server tunnel, returns
HlsTunnel
objectpath
- path to be servedregion
- can be 'us', 'ap' or 'eu' (default: 'us')subdomain
- tunnel subdomain (default: random)reservedDomain
- reserved domain either custom domain or subdomainbasicAuth
- protect the tunnel with basic authentication in the form ofuser:pass
eventCallback
- tunnel events callback, see below- NOTE: if
reservedDomain
is supplied,subdomain
andregion
are neglected
- tls(options) - create a TLS tunnel, returns
HlsTunnel
objectregion
- can be 'us', 'ap' or 'eu' (default: 'us')to
- address to forward to (default: 127.0.0.1:8080)subdomain
- tunnel subdomain (default: random)reservedDomain
- reserved domain either custom domain or subdomaincrt
- tls certificate pathkey
- tls key patheventCallback
- tunnel events callback, see below- NOTE: if
reservedDomain
is supplied,subdomain
andregion
are neglected
- tcp(options) - create tcp tunnel, returns
TupTunnel
objectregion
- can be 'us', 'ap' or 'eu' (default: 'us')to
- address to forward to (default: 127.0.0.1:8080)port
- public port for your tunnel (default: random)reservedEndpoint
- reserved endpointeventCallback
- tunnel events callback, see below- NOTE: if
reservedEndpoint
is supplied,port
andregion
are neglected
- udp(options) - create udp tunnel, returns
TupTunnel
objectregion
- can be 'us', 'ap' or 'eu' (default: 'us')to
- address to forward to (default: 127.0.0.1:8080)port
- public port for your tunnel (default: random)reservedEndpoint
- reserved endpointeventCallback
- tunnel events callback, see below- NOTE: if
reservedEndpoint
is supplied,port
andregion
are neglected
- kill() - close all the tunnels and stop LocalXpose process
HlsTunnel Class
(HLS stands for HTTP/TLS)
Methods
- close(options) - close the tunnel, returns a promise
Properties
ticket
- tunnel idto
- address to forward toproto
- protocolhttp
ortls
addr
- the tunnel address (e.g.hello-world.loclx.io
)region
- tunnel regionstatus
- tunnel statusnull
,running
,stopped
orclosed
basicAuth
- username and password of the tunnelcrt
- tls certificate path (tls tunnels only)key
- tls key path (tls tunnels only)hostheader
- host header valuepath
- file server path
TupTunnel Class
(TUP stands for TCP/UDP)
Methods
- close(options) - close the tunnel, returns a promise
Properties
ticket
- tunnel idto
- address to forward toproto
- protocoltcp
orudp
addr
- the tunnel address (e.g.us-1.loclx.io:27002
)region
- tunnel regionstatus
- tunnel statusnull
,running
,stopped
orclosed
hostname
- hostname (e.g.us-1.loclx.io
)port
- public port number (e.g.27002
)
Event Callback
Callback will be called for every event triggered by the tunnel.
function callback(event,data)
Argument event
will be one of the follwoing
Name | Description |
---|---|
EVENT_RUNNING | Emitted when the tunnel is started successfully |
EVENT_RECONNECTING | Emitted when the connection is lost and trying to reconnect |
EVENT_RECONNECTED | Emitted when the tunnel is reconnected successfully |
EVENT_ERROR | Emitted when there is an error |
EVENT_CLOSED | Emitted when the tunnel is closed |
EVENT_MESSAGE | Emitted when there is a message (e.g. the forwarded address is unreachable) |
Argument data
will be as follow:
{
tunnel, // tunnel object (HlsTunnel or TupTunnel)
msg, // message comming from the `EVENT_MESSAGE` event
error // error object
}
Full Example
const LocalXpose = require('localxpose')
const client = new LocalXpose('YOUR_ACCESS_TOKEN');
(async function(){
let httpTunnel = await client.http({
to: "127.0.0.1:4125",
subdomain: "hello",
eventCallback: callback
})
setTimeout(function () {
httpTunnel.close()
},10000)
})()
function callback(event,data){
switch(event){
case "EVENT_RUNNING":
console.log(`tunnel ${data.tunnel.addr} is started`)
break
case "EVENT_ERROR":
console.log(data.error)
break
}
}
Development
Setup
Run npm install
inside the repository to install all the dev dependencies.
Testing
Once all the dependencies are installed, you can execute the unit tests using npm test