The Spanner

My one man mission to create a social coding network is going well, if you read this blog previously you’ll remember my attempts at a JavaScript sandbox until I finally settled on JSReg as a method. I’ve refined the process of creating tags after trying to build them myself using the editor.

How to create a tag

Login to Hackvertor and click “Create tag” this will give you a JavaScript editor with a default blank tag. I’ve added this as guidance, the first part of the sample is a simple if statement that checks the first param for something. Params are tag params that the user can change when using your tag, the editor has these three params on the left hand side so that you can test. Lets say your tag supports one parameter and either encode or decode, place encode in the first param box and you can test that state in the editor.

You might notice that the sample tag uses an anonymous function, this makes it easier for you to return the output from the tag. You don’t need one for simple tags but I recommend you use one when developing more complex ones.

The left hand side also contains “name” which is the name of your tag and category to appear in the application home page, the help text at the bottom lets you describe what your tag and params does. This is useful for the user as before they add the tag they can hover over it and read what it does.

Every tag extends the special object property “HV” which allows you to reuse your code and others. Lets say you want to reverse some text, rather than writing this yourself you can use the HV object like so:-

code = code.HV('reverse');
(123).HV('reverse')

Notice this works with any object as demonstrated in the second part of the sample code.

In order to work with user input a special variable is automatically assigned called “code” you can test user input by placing something in the user input box above the editor. This automatically gets assigned to “code” and allows you to test your tag. Each time you modify the tag the code is automatically executed and any syntax errors will be reported.

You can also look at previous tags for inspiration.

Limitations

Like anything the sandbox isn’t perfect, one of the most common problems you’ll encounter will be arrays. When using arrays you need to make sure you define them using Array() not [] as it is assumed in the sandbox that [] is a object property accessor. Using the Array constructor can be tricky because Array(1) creates an array with a length of 1 but NOT with a value of 1 in the first element.

Try not to use complex for loops and avoid for..in loops where possible until the sandbox handles loops more effectively.

Special powers

I’ve added a fun element to creating tags. When you add tags in Hackvertor you get points and a special, when someone votes for your tag you get points, if a tag is malicious or bad you can get points removed. When you reach a certain status with the amount of points you’ve accumulated you’ll be able to perform a special power.

There are currently 7 special powers and depending what status you are you’ll be able to use them on weaker foes. This feature is experimental and I could remove it change it slightly depending on the results. Points can also be negative and will be awarded if a user tries to do some vote rigging or maybe forgets to select a user to perform a special power on. You’ve been warned

I’m not a developer any more so I find it difficult to update the experiments I’ve been working on but I managed today to upload the work I’ve done with JSReg and update Hackvertor. They are both integrated closely together because Hackvertor allows untrusted Javascript using JSReg.

The recent upgrade to JSReg allowed me to upload the Hackvertor changes I did a while ago, it is now very nice and easy to share code between users. At the moment registration is disabled but I plan to enable it once I’ve figured a way to stop user’s overloading the tag list.

You can see how the integrated JSReg parser works by visiting Public Hackvertor this will eventually replace the original one now online. There are only a limited set of tags as I’ve not had time to code them all but we have a couple of users on there that might start adding code if they haven’t forgotten their password =)

I found the untrusted Javascript feature difficult to code as sharing each tag inside a tag for example would require some tricky Javascript but I think I’ve managed to pull it off. I’ll document the JSReg stuff here and how Hackvertor allows tag objects inside tags.

Playing nice with JSReg

In order to use the parser effectively we need to be able to inject our own objects into the sandboxed environment without compromising the security of the sandbox. To do this JSReg supports some extension functions which allows you to inject a object directly. The following code sample shows you how to do it:-

parser.extendWindow('$tags$',(function(tags) {
  return function(obj, callback) {
		var code = obj.$code$;
		var tag = obj.$tag$;
		var param1 = obj.$param1$;
		var param2 = obj.$param2$;
		var param3 = obj.$param3$;
	if(!tags.hasOwnProperty(tag)) {
		return null;
							}
return tags[tag].execTag(code,callback,[param1,param2,param3]);
}
})(window.Hackvertor.tags)
);

So here the “parser” is the JSReg parser, we use the extendWindow function to place a “$tags$” object within the sandbox. Notice the $ prefix and suffix, this is how JSReg protects objects/properties. We use a closure to send a Hackvertor Tag object to the sandbox which passes it a function that accepts a tag object and a callback. Hackvertor now uses callbacks for each tag, this allows conversions to be run in sequence without waiting for each function to return the output.

A simplified version of this can be seen below, this time we assign a value from a dom object outside of the sandbox to a reference inside the sandbox.

parser.extendWindow('$code$',document.getElementById('input').value);

The new Hackvertor

All tags are now user definable! Each tag can have up to three parameters, provide some help text and call existing tags from inside the sandbox To create a tag you simply have to return some output, inside a tag it has some special variables that are automatically assigned when a tag is called. The special variables are listed below:-

code, params, tags

The code refers to the original text passed to your tag, this could be plaintext or some text that has been transformed by a previous tag. The params is a simple numeric indexed array which refers to any params supplied by the user so for instance if you tag supports 1 param, you can refer to it inside your tag as param[0]. Tags contains the Hackvertor tag reference mentioned previously and allows you to call existing tags without having to write the same code over and over. I will show below how you to call the base64 tag that currently exists in the Hackvertor tag space.

tags({code:'abc',tag:'base64',param1:'encode',param2:'',param3:''},function(result) {alert(result);})

So this will call the tags function defined by extending the sandbox, it accepts a object and callback as it’s arguments. I send a string ‘abc’ and use the tag ‘base64′ I supply one param ‘encode’ and then use the callback to get the result of the conversion.