Router

Telehash apps usually need one or more mesh routers to assist in establishing p2p links. You can run your own router via npm start, manually via node bin/router.js, or just router if you did an npm install -g. The JSON object from the router output can be passed in to the mesh.link({...}) function (shown below) or stored in your own links.json locally.

In node, the id and links can be strings pointing to local filenames that will be auto-loaded. In the browser they can be string keys to localStorage. Those locations will also be generated and kept in sync for any changes.

Establishing Links

A link can be created with just a hashname (this requires a router to assist):

var link =mesh.link(hashname);
// will be called when link status changes, err is undefined when link is uplink.status(function(err){
if(err) {
console.log('disconnected',err);
return;
}
console.log('connected');
// can do any other link.* methods
});

A link can also be establish directly (no router required):

var link =mesh.link({keys:{},paths:{}});

The .link({args}) will also take an argument of "jwt":"..." to include a JWT in the link request for identifying/authorizing the sender.

Accepting/Authorizing Links

When an incoming link is requested the local app must decide if it accepts that link. By default all unknown links/senders are ignored and never responded to in order to protect the privacy of the recipient.

To process incoming link requests:

mesh.accept=function(from){};

The accept function will always be called with a from object that includes the hashname of the sender and any additional details about the request including keys, paths, and all handshake types received as hset.

To authorize/accept the request, simply perform a mesh.link(from) and it will respond and create the link.

Routing

By default every endpoint will assist with routing between any of the active links in its mesh in order to maximize connectivity, but this requires the routing endpoint to be connected to both which may not always be the case.

One or more links can be dedicated routers for all other link requests, and/or any link can be used as a router for another:

mesh.router(link); // any link can be used as a default routermesh.link({...,router:true}); // another way to set a link as a default router from the startlink.router(link); // just one link can be used as a router for anothermesh.link({...,paths:[{type:'peer',hn:'linked'}]}); // including a peer path to an already-linked hashname will automatically use it as a router

Whenever a default router is added, it will also be advertised to other links as a peer path for this endpoint.

Discovery Mode

Discovery mode enables any network transport to send un-encrypted announcements to any other endpoints that are available locally only. This can be used to automatically establish a link to a local peer when there is no other mechanism to exchange keys, such as when they are offline.

It is important to note that this should be used sparingly, as anything on a local network will be made aware of the sending hashname. While this is generally very low risk, it should not be left on by default except in special cases.

While discover is enabled, mesh.accept will be called for all discovered local endpoints.

Optional args and a callback (to know once discovery is enabled on all the transports) can be passed in:

mesh.discover({args},done);

The args can include:

jwt - a JWT to include in the announcement to help identify the sender

custom per-transport discovery options may be passed in

Extensions

Most functionality is added by extending the core library to support additional channels and expose more methods. The built-in extensions live in the ext folder, but additional ones can be added by the app.

path - check and synchronize all network paths on a link:

link.ping(function(err, latency){
// error if it failed// latency is number of milliseconds if it succeeded (may be 0)
});

link.stream(); // returns a new duplex stream to this link, optional args are sent to the link during creationfs.createReadStream(filein).pipe(link.stream()); // can be used as a pipe// to receive incoming streamsmesh.stream(function(link, args, cbAccept){
// link is who it came from// args is set if any were given by the sender// call cbAccept(err); to cancel// cbAccept() returns a duplex streamcbAccept().pipe(fs.createWriteStream(fileout));
});

chat - send and receive one-to-one or group chat messages

draft implementation, works but is minimal

// create or set args.id and args.leader to join a new chatmesh.chat(args, profile, function(err, chat){
chat.inbox; // incoming message streamchat.outbox; // stream to send messageschat.profiles; // hn->profilechat.messages; // cache/index by message idchat.log; // ordered known chat history ["id2", "id1", ...]chat.join(link); // leader can use to accept/invite others
});
// set handler for when invited to a chatmesh.invited(function(link, profile){});