Discover Hotgun: Do you search clean, dirty, classy or nerdy?


The First Person Search Engine

An unnamed space marine

First of all, if you're looking for a videogame you're in the wrong place. Or not. That depends. Anyway, HotGun is a Javascript library inspired by peer-to-peer networks. It implements some kind of simple and weird data search engine that doesn't need any centralized index. And no HTML5 needed this time.

How To Play

HotGun works mainly like a shotgun in a FPS.

  1. Bullets are loaded into HotGun, so a first batch of peer URLs is loaded by the HotGun client via a JSONP call.
  2. Trigger is pulled. Bullet Hell. Peer URLs are called via JSONP call. With various misses (timeouts, missing URLs) and hits.
  3. Looting. Hit peers will leave more bullets and items: some of them will be useful and picked up and some other will be left - can be useful later.
  4. Repeat until the game is over. More peers, more looting. The game ends when the time is up or we've enough useful items or there isn't anybody to shoot.
  5. Debriefing, score and promotion. Once interesting items are collected, they are ranked and a score is given.
  6. Savegame and continue. High ranked items are picked up and unuseful junk is removed. The same search can be continued later, looking for more peers and useful items.
  7. That's all - everything happens into the client rather than into the server as usually happens. Search criteria, results scoring and filtering are customizable for every search but HotGun has its own, so it works out of the box.


    HotGun is based on JSONP calls to random servers. And that's really really REALLY bad, since any of the peer can execute Javascript code into the page. But... wait. Are you going to use this for sharing data with your friends or as a simple client side cluster or just for having some fun, aren't you? Surely, the longest is the game the better but is risky too.

    HotGun is not SHotGun

    HTML5 is offering a set of solutions for making cross-domain calls more secure, like CORS. But luckly CORS needs the particular header Access-Control-Allow-Origin to be sent together with server answer and I wanted to write something that works both online and offline without any server at all. JSONP allows to mix local repositories with remote one, creating some interesting scenarios (some of the data can still be private for not connected clients). That's why HotGun is missing its "S" - for making "Secure HotGun" a day. But not now - I just wanted to have some fun :)

    Register your copy

    HotGun is MIT/GPL2 licensed, so you can play as you wish. If you just want to create a peer, host a file like this in your webserver, making sure that your items section is describing something interesting. You can share the absolute URL of your file with others and add your friend's URLs into the peers section in order to make your (and your friend's) network grow.

    If you're going to run your personal search engine (or you're going to use HotGun for something else), start including hotgun.js in your webpage, and, when the page is loaded, add a peer to HotGun and start searching like this:

    HotGun.addPeer( "http://your/peer.js/file" ); "keyword" , function(search) { console.log(search.results) } );

    If you start searching without adding a peer with HotGun.addPeer the peer.js file hosted in the same place of the included hotgun.js is automatically added as peer. So, if you're including hotgun.js from this site, a small sample network you can use for playing a little is loaded. The same happens when you decide to host both a peer.js and a hotgun.js: whoever will include hotgun.js from your site will be able to start searching your network out-of-the-box without specifying anything.

    HotGun allows to specify number of needed results, maximum duration of a search, filtering criteria and some more.{
      query:"apples", // Look for the keyword "apple"
      resultsize:20, // Give me at least 20 results
      duration:5000, // Stop searching after 5000msec
      maxdepth:2, // Don't go deeper than 2 sub-peers
      onfilter:myfilter, // Filter each hit using this custom function
      onpeer:mypeercallback, // When a new peer is reached call this callback function
      onresult:myresultcallback, // When a valid result is found call this callback function
    } , function(search) { console.log(search.results) } );

    Obviously you don't have to specify all of them every time. There are more parameters - have a look to hotgun.js for more details.

    Oh, yeah. You want to download the whole thing. Download the 0.1 version here, which includes HotGun sources, a small demo network of peers, a bunch of examples of search frontends and - well - everything in this site.

    Shareware episodes

    Probably HotGun demos aren't the most exciting thing in the world, since the bigger is the network the better are the results. Anyway, I've put together some frontends for giving some ideas on how HotGun can be used... on a really small sample network.

    If you prefer a clean search which makes your fair and zen, have a look to HotGun Clean, which searches websites links shared into a HotGun network.

    Do you feel that most of your searches are dirty? Okay, feel dirtier with HotGun Dirty, a filesharing styled frontend for searching images, audio and videos.

    You can share links, yeah. But data too. Data searches are way more classy than file and site searches. That's why you can search few books in HotGun Classy.

    But I know that you'll love HotGun Nerdy, a frontend with tons of logs, texts, stats and a command line. Helped a lot during development... why not to include it with the bunch?

    All demos also work just hitting the search button without setting any query (or typing just s and hitting enter into the command line, for HotGun Nerdy), so you can start checking what's inside the network and then doing some filtering.


    HotGun was born in one of my common cases of solution-before-problem but, this time, I decided to deveop this as a proof-of-concept instead of waiting for an useful use case. There are some drawbacks on using JSONP techniques for contacting unknown sites and on downloading full indexes of stuff at every search but... who cares? I've found this funny and, in some cases, can be useful too for distributing contents - for example - if you want to be unaware of the availability of the originating source and don't want to put together a complex server side network. If you found some productive way of using this, you had some fun or you did some patch, please contact me! All my contacts are at!


    Thanks for Nerdissimo for helping me on some quick test on HotGun and for sharing ideas. And thanks to Bianca because is ever on my side.